* Copyright (C) 2025 Red Hat, Inc.
*
* SPDX-License-Identifier: LGPL-2.1-or-later
*/
- progress reporting
- array splicing via value handles
- different validation rules for different actions
*/
meant to save us from having to think through all the details every
time of how a dialog should work exactly and to allow us to just
get on with the business logic.
The framework has two parts (like git): plumbing and porcelain.
The plumbing takes care of the state management of dialog values,
asynchronous and debounced input validation, progress feedback and
errors from actions, etc. It's basically a couple of rather
complicated JavaScript classes that work in the background. This
is the part we don't want to implement from scratch for every
dialog.
The porcelain is a set of React components that integrates with the
plumbing. They are usually very straightforward and easy to
write. If none of the existing ones works for you, just write a new
one that does. But they are boilerplatey, so having common ones for
common things like text input fields makes a lot of sense, too.
Here is an example of a simple dialog that prompts for some text
and writes it to the journal:
interface LoggerValues {
text: string;
}
const LoggerDialog = () => {
const Dialogs = useDialogs();
function validate() {
dlg.field("text").validate(v => {
if (!v)
return "Text can not be empty";
});
}
async function apply(values: LoggerValues) {
await cockpit.spawn(["logger", values.text]);
}
const dlg = useDialogState({ text: "" }, validate);
const text_field = dlg.field("text");
return (
<Modal position="top" variant="medium" isOpen onClose={Dialogs.close}>
<ModalHeader title="Logger" />
<ModalBody>
<DialogErrorMessage dialog={dlg} />
<Form>
<FormGroup label="Log message">
<TextInput
value={text_field.get()}
onChange={(_event, val) => text_field.set(val)}
/>
<DialogHelperText field={text_field} />
</FormGroup>
</Form>
</ModalBody>
<ModalFooter>
<DialogActionButton dialog={dlg} action={apply} onClose={Dialogs.close}>
Log
</DialogActionButton>
<DialogCancelButton dialog={dlg} onClose={Dialogs.close}/>
</ModalFooter>
</Modal>
);
};
const LoggerButton = () => {
const Dialogs = useDialogs();
return (
<Button onClick={() => Dialogs.show(<LoggerDialog />)}>Open logger dialog</Button>
);
};
This uses some porcelain for the error message and footer buttons,
but none for the text input field. There is a "DialogTextInput"
porcelain component that could have been used to make this example
even more concise. But we didn't use it here just to show how input
form elements hook into the plumbing.
PLUMBING API
The central piece of the plumbing API is the useDialogState hook
(and it's async variant useDialogState_async). You can think of it
as "useState" on steroids.
- Like useState, useDialogState gives you a place to store state in
a function component, and gives you a way to change that state
and trigger a render so that the new state is put on the screen.
- Unlike useState, you are only supposed to have a single
useDialogState and put all of the state in a single JavaScript
object. And instead of a single setter function, there are ways
to get setters to individual parts of that object via "handles".
- The handles work also for nested objects and arrays. You can get
a "sub handles" for a single key from a handle for an object, for
example.
- The useDialogState hook also provides for global validation of
the state object, at exactly the right times, and communicates
the result of that to the "Apply" button, for example.
- The handles to parts of the state give you access to everything
needed to implement a part of the dialog form: The current value,
a method to change the value, and any validation errors that
should be shown. This makes it possible to write encapsulated
components that can be cleanly combined into full dialogs.
- The useDialogState hook also provides for miscellaneous things
like transporting the exception from running the "Apply" action
to the error message in the dialog.
Here is a speedrun of the plumbing API:
- dlg = useDialogState(init, validate)
This is a React hook that creates a new instance of the plumbing
machinery. It also causes the current component to re-render
appropriately.
The values of the input fields of a dialog are stored in a
JavaScript object, and that object is initialized to "init", or the
result of calling "init" if it is a function. The actual values of
a dialog can be anything, strings, number, other objects, arrays,
etc, to an arbitrary depth.
The "validate" parameter is a function that performs input
validation. It has to follow a very specific code pattern, which is
explained below.
There is a variant of useDialogState for asynchronous
initialization, called useDialogState_async. It takes a async init
function and returns null until that function has resolved. You
should render a spinner in the dialog while "dlg" is null.
If the asynchronous "init" function throws an exception, "dlg" is
set to a DialogError object. In that case you should render the
error in the dialog.
The porcelain components that do not work on actual dialog values,
such as DialogActionButton and DialogErrorMessage, can deal with
their "dialog" properties being null or a DialogError, and will do
the right thing.
The return value of useDialogState, "dlg", has a number of fields
and methods.
- handle = dlg.field(name)
- handle = dlg.field(name, changed_func)
This returns a handle for a specific field of the dialog
values. Using handles like this becomes convenient when there are
nested values, and when writing reusable porcelain components. They
also work well with TypeScript. For simple dialogs they might feel
a bit clunky.
The second argument, "changed_func", is optional. If given, it
should be a function and that function will be called whenever the
dialog value is changed via the returned handle (and the returned
handle only). It might also be called some time later, when
"set_debounced" is used.
- handle = dlg.top()
- handle = dlg.top(changed_func)
Get a handle for the whole value object. The usual
"dlg.field(name)" call is actually just a shortcut for
"dlg.top().sub(name)". But since that looks quite obscure in
simple dialogs that only have one level of values, we have the
"dlg.field(name)" shortcut as well. This whole-value handle is
useful for "dlg.top().at(...)", see below, or for notifications
that trigger for each and every change.
- dlg.values
The current whole dialog value object. This is the same as
"dlg.top().get()", but accessing it is common enough in simple
dialogs that exposing it directly makes sense.
The object will never be mutated by the plumbing itself. When it
needs to be changed, a whole new value object is constructed and
assigned to "dlg.values".
- handle.get()
Get the current value of a value handle.
- handle.validation_text()
Get the current validation error message for this value. This is
"undefined" when there is no message.
- handle.set(val)
Set the current value of a value handle. This will re-render the
dialog, and do input validation as necessary and all the other
things that you don't need to think about.
This is actually the same as "handle.set_debounced" with a delay of
0, see below.
- handle.set_debounced(val)
- handle.set_debounced(val, delay)
Set the current value of a value handle immediately as described
above for "handle.set", and render the dialog. But validation and
calling of the "changed" functions happens only after "delay"
milliseconds.
When "delay" is omitted, it defaults to a sensible value for
debouncing keyboard input.
- handle.notify(changed_func)
Return a new handle for the same dialog field that "handle"
represents, but call "changed_func" whenever the field is changed
via the new handle.
- handle.sub(name_or_index)
- handle.sub(name_or_index, changed_func)
Get a handle for a nested value. When the current value is an
object, you should pass the name of a nested field. If it is an
array, pass the index of the desired element. See "dlg.field()"
above for more information about handles.
- handle.get_async((val, signal) => ...)
- handle.set_async((val, signal) => new_val)
These are for running asynchronous code. The dialog waits for all
asynchronous tasks started by these functions to be finished before
running the action function. When the dialog is cancelled, they
all get cancelled.
The return value of "handle.set_async" is made the new value of the
field, but only if the value of the field hasn't changed in the
meantime. There can only be one currently active "set_async" call.
If you call it again before the previous one has finished, that
previous call will be cancelled at that point, just as if the field
value had changed.
The "handle.get_async" function is a slight variation on this. It
is meant to perform asynchronous computations that do not modify
the field value itself, but have some other side effects. There
can be more than one call active at a given time. They only get
cancelled when the value of the field changes.
The asynchronous tasks must be careful to only perform their side
effects when they have not been cancelled yet. This can be done
with the help of their "signal" parameter, which is a standard
AbortSignal.
Because of the way JavaScript works, the asynchronous functions
keep running and they need to voluntarily inspect "signal.aborted"
to figure out when they should stop. They can also use all other
features of a AbortSignal, of course, such as setting
"signal.onabort", adding event listeners, etc.
- handle.at(witness)
Get a handle with a narrowed type for "handle". The new handle
works like "handle" and modifies the same place in the dialog value
object, but it's type will be the type of "witness". This is
useful to carry over type inference into value handles. The
general pattern is:
const val = handle.get();
if (some_type_narrowing_condition(val)) {
const narrowed_handle = handle.at(val);
...
}
- handle.add(val)
If the current value is an array, append "val" at the end.
- handle.remove(index)
If the current value is an array, remove the element at "index".
It is important to use this function instead of just "handle.set()"
with an appropriately modified array. By using this function, the
plumbing is able to keep its internal state in synch, which is
especially important for asynchronous validation and "changed"
functions.
However, it is okay to just replace an array with a different
array, so you are not strictly required to use this function. But
doing so might look to the validation machinery as if each and
every element of the array has just changed, and it will do a lot
of needless validations all over again.
- handle.map(func)
If the current value is an array, map "func" over handles for its
elements. This is nice for creating React components for arrays.
- handle.forEach(func)
If the current value is an array, call "func" with handles for each
of its elements, in order. This is nice for "validate" functions.
Now back to the fields and methods of the dialog state.
- dlg.busy
- dlg.actions_disabled
- dlg.cancel_disabled
Boolean flags that indicate which parts of the dialog should be
disabled. The porcelain should of course look at these and do the
right thing.
- dlg.error
The most recent error thrown by an action function. This can be
any kind of JavaScript value, but the idea is that it is something
with a "message" field, or a DialogError instance. The
DialogErrorMessage porcelain component will do the right thing with
these kind of error values.
- dlg.run_action(func)
Waits for all asynchronous updates and input validation to be done
and if that was successful, calls "func" and puts the dialog into a
"busy" state while it runs. When "func" throws an error, it is
caught and stored in "dlg.error".
"dlg.run_action" returns true when validation has passed and "func"
has completed without throwing an error.
All state changes via "field.set()" are denied while "func" is
running. This is done to prevent the user from interacting with the
dialog while an action runs. But there is nothing fundamentally
wrong with programmatically changing dialog state as part of an
action. If you want to do that, write code like
if (dlg.run_action(...))
dlg.field("xxx").set(...)
- dlg.cancel(onClose)
Does whatever should happen when the "Cancel" button is
clicked. When an action is running, it will call the "cancel
function" (see below). Otherwise all validation and update tasks
are cancelled and the dialog is closed by calling "onClose".
- dlg.set_cancel(func)
Arranges for "func" to be called when the cancel button is clicked.
You should call this only from a action function passed to
"run_action" and you need to take care to reset this via
"dlg.set_cancel(null)" once the cancel function should no longer be
called. When a action function finishes or throws an error from
within "dlg.run_action", the cancel function is automatically
reset.
VALIDATION
Input validation is done by a single, central function for the
whole dialog. This has been done so that there is a central place
that establishes the "shape" of the dialog values. This is
important for dialogs that have optional parts.
If such an optional part of the values has failed validation
earlier, but has subsequently been removed from the dialog by the
user, the plumbing needs to know that it should now ignore this
failed validation. But the code that knows what is currently in the
dialog is the render function that instantiates all the field input
components (like TextInput). This hacker here has found no reliable
and non-magical way to connect what the render function actually
does with the plumbing machinery. So everyone has to write a big
validate function now that duplicates this, sorry!
The formal job of the validation function is to call the "validate"
method (or "validate_async") of all relevant dialog value handles.
If and only if a validation failure of a field should prevent
running the action function, should the validate function visit it.
- handle.validate(v => ...)
This might call the given function with the current value of the
handle. If it passes validation, the function should return
"undefined". If it fails, the function should return a string with
the appropriate message. This message will be available from the
"handle.validation_text" method and should be shown by the React
component for this value, of course. Returning an error here will
also disable the action buttons.
The "v => ..." function is only called when necessary, when the
value has actually changed.
A validation function can also return an object with validation
errors for its sub-fields. This is useful if multiple fields need
to be validated together. Consider this example:
field.validate(v => {
if (v.mode != "auto" && v.size == 0)
return { "size": "Can't be zero in manual mode." }
});
If your validation function needs to communicate out-of-band with
your action function (maybe to pass the results of some expensive
operations that you don't want to repeat in your action function),
then you can modify field values via calls to "handle.set". (Be
careful not to create endless validation loops!)
- handle.validate_async(async (v, task) >= ...)
Same as "handle.validate", but the function is asynchronous and
"dialog.run_action" will wait for these functions to complete
before actually carrying out the dialog action.
UPDATES
Sometimes dialog values need to be changed in reaction to other
changes. For example, when the user selects a ISO for creating a
new virtual machine, you might want to run some code that detects
the OS on that ISO and then adapts the rest of the dialog to the
minimum storage requirements of the OS. Sometimes you can do
everything at render time, but sometimes you might want to run some
code as part of the event handler for the user action, and
sometimes you need to run asynchronous code.
(Don't use useEffect, please, just stick the code into the event
handler.)
It's okay and simplest to just put that code right next to the call
to "handler.set()". If that call is in a porcelain component (as
it probably often will be), you can pass a "changed_func" when
creating the handle for that porcelain component with
"handler.sub()" or "dialog.field()". For example:
function plate_changed(val: string) {
console.log("NEW LICENSE PLATE", val);
}
return (
<DialogTextInput
label="License plate number"
field={dlg.field("plate", plate_changed)}
/>
);
The function "plate_changed" will be called whenever the user
changes the "plate" field via the DialogTextInput (subject to
debouncing). The "plate_changed" function will not be called
when the "plate" is changed in other places. If that should
happen, you have to arrange for it explicitly.
Functions like "plate_changed" can and should modify the dialog
fields via calls to "handle.set()".
If you want to run asynchronous code, you can do so with
"handle.set_async()" or "handle.get_async()". For example, if you
want to asynchronously fetch the car model for a given license
plate from a database, you can do it like this:
function plate_changed(val: string) {
dlg.field("model").set_async(async () => await fetch_model(val));
}
When arrays are involved, dialog fields can move around while your
asynchronous update function runs. To help with this, handles will
keep referring to the same field even if it moves around in its
array.
TESTING
Our automated tests will want to drive the dialogs created by this
framework, of course. To support this, the various DOM elements
instantiated for a dialog should be decorated with structured "id"
attributes. The code that instantiates an element can get suitable
IDs for dialog value handles with the following function:
- handle.ouia_id(tag)
This will return a predictable string for the value handle. This
is suitable for the "data-ouia-component-id" attribute of DOM
elements associated with "handle". The "tag" parameter can be used
to generate multiple IDs if a component has multiple interesting
DOM elements. The "tag" parameter defaults to "field", see below.
There is a support library for use by the tests that can generate
the same IDs, and there are also some guidelines for how to use
these IDs:
- The main input element (text input, form select, ...) should use
the "field" tag.
- The helper text should use the "helper-text" tag.
- A set of radio buttons should use a different tag for each
button. Whatever makes sense in the specific case.
- ...
PORCELAIN GALLERY
Here are some noteworthy React components that integrate with the
plumbing API.
- <DialogErrorMessage dialog={dlg} />
This creates an appropriate Alert for "dlg.error", if it is set. It
works well with instances of DialogError, and all usual errors
thrown by the Cockpit API.
In addition to a proper DialogState, the "dialog" property can be
anything returned by "use_DialogState_async".
If given one the of Cockpit API errors, the title of the Alert will
be a generic "Failed" text. If you want more control, use a
DialogError.
A DialogError contains a title and details, and the details can
come from another error. For example:
try {
await cockpit.spawn(["/bin/frob", "--bars"])
} catch (ex) {
throw DialogError.fromError("Failed to frob the bars", ex);
}
You can also construct a DialogError directly from title and
details:
throw new DialogError("Failed to frob", <pre>...</pre>);
In that case, the details can be any React node.
- <DialogActionButton dialog={dlg} action={func} onClose={close_func}>
This will produce a action button for a dialog that correctly disables
itself according to the state of "dlg".
In addition to a proper DialogState, the "dialog" property can be
anything returned by "use_DialogState_async".
When clicked, "func" will be run via "dlg.run_action". If "func"
completes successfully, "close_func" is called to close the dialog.
- <DialogCancelButton dialog={dlg} onClose={close_func} />
This will produce a cancel button for a dialog that correctly
disables itself according to the state of "dlg".
In addition to a proper DialogState, the "dialog" property can be
anything returned by "use_DialogState_async".
Clicking it will either just close the dialog by calling
"close_func", or run the cancel function provided by the currently
running action function (if there is any).
- <DialogTextInput label="Name" field={dlg.field("name")} ... />
This will produce a TextInput in a (optional) FormGroup that will
manage the given value handle. The "label" property is optional
and omitting it will also omit the FormGroup.
- <DialogCheckbox label= field= .../>
For a single checkbox that drives a boolean.
- <DialogRadioSelect label= field= options= .../>
For a group of radio buttons. The options can be disabled and have
explanations.
- <DialogDropdownSelect label= field= options= .../> </>
For a simple dropdown select. Options can not be disabled or have
explanations.
- <DialogDropdownSelectObject label= field= options= option_label= />
A variant of the simple dropdown select from above where the options
can be of any type whatsoever, such as something directly from your
data model. A simple case is selecting from an array of strings. In
that case you can omit the "option_label" function.
*/
import React, { useState, useId } from "react";
import { useObject, useInit, useOn } from 'hooks';
import { EventEmitter } from 'cockpit/event';
import cockpit from "cockpit";
import { Button, type ButtonProps } from "@patternfly/react-core/dist/esm/components/Button/index.js";
import { FormGroup, type FormGroupProps, FormHelperText } from "@patternfly/react-core/dist/esm/components/Form";
import { TextInput, type TextInputProps } from "@patternfly/react-core/dist/esm/components/TextInput";
import { Alert } from "@patternfly/react-core/dist/esm/components/Alert/index.js";
import {
HelperText, HelperTextItem, type HelperTextItemProps
} from "@patternfly/react-core/dist/esm/components/HelperText";
import { Checkbox } from "@patternfly/react-core/dist/esm/components/Checkbox";
import {
FormSelect, FormSelectOption, type FormSelectProps,
} from "@patternfly/react-core/dist/esm/components/FormSelect";
import { Radio } from "@patternfly/react-core/dist/esm/components/Radio";
import { InputGroup, InputGroupItem } from "@patternfly/react-core/dist/esm/components/InputGroup/index.js";
import { EyeIcon, EyeSlashIcon } from "@patternfly/react-icons";
import { Tooltip } from "@patternfly/react-core/dist/esm/components/Tooltip";
const _ = cockpit.gettext;
function debug(...args: unknown[]) {
if (window.debugging === "all" || window.debugging?.includes("dialog"))
console.debug("dialog:", ...args);
}
type ArrayElement<ArrayType> =
ArrayType extends readonly (infer ElementType)[] ? ElementType : never;
function toSpliced<T>(arr: T[], start: number, deleteCount: number, ...rest: T[]): T[] {
const copy = [...arr];
copy.splice(start, deleteCount, ...rest);
return copy;
}
try to return errors for sub-fields that don't exist. We can
construct a type that describes this (by recursively mapping all
field to strings, essentially), but TypeScript will not ordinarily
prevent a validation function from returning something that also
has other fields, because it does only do "excessive property
checks" for literals that are assigned to locations with a known
type. Example:
interface ComboValue {
size: number;
unit: string;
}
dlg.field("combo").validate(v => {
return {
size: true, // TypeScript error here as expected, because true is not a string
unt: "No such unit", // Want a TypeScript error here bc there is no "unt" in the type, but won't happen
}
});
We would need to explicitly annotate the validation function with
the right return type like so:
dlg.field("combo").validate((v): DialogValidationResult<ComboValue> => {
return {
unt: "No such unit", // Now we get an error.
}
});
But I doubt that people will be happy to write out their type like
this every time...
*/
export type DialogValidationResult<T> = (
T extends object
? ({ [Property in keyof T]+?: DialogValidationResult<T[Property]> } & { ""?: undefined | string }) | undefined | string
: undefined | string | { ""?: undefined | string }
);
function state_path(state: DialogFieldState): string {
const p = state.parent ? state_path(state.parent) : "";
const t = String(state.tag);
return p ? `${p}.${t}` : t;
}
export class DialogField<T> {
#dialog: DialogState<unknown>;
#state: DialogFieldState;
#getter: () => T;
#setter: (val: T) => void;
#trigger: () => void;
constructor(
dialog: DialogState<unknown>,
state: DialogFieldState,
getter: () => T,
setter: (val: T) => void,
trigger: () => void,
) {
this.#dialog = dialog;
this.#state = state;
this.#getter = getter;
this.#setter = setter;
this.#trigger = trigger;
}
validation_text(): string | undefined {
return this.#state.validation_text;
}
get(): T {
return this.#getter();
}
set(val: T): void {
this.set_debounced(val, 0);
}
set_debounced(val: T, delay?: number): void {
this.#dialog._abort_state_tasks(this.#state, true);
this.#setter(val);
this.#dialog._set_debounce(this.#state, delay === undefined ? 500 : delay, () => this.#trigger());
}
ouia_id(tag: string = "field"): string {
return "dialog-" + tag + "-" + state_path(this.#state);
}
map<X>(func: (val: DialogField<ArrayElement<T>>, index: number) => X): X[] {
const val = this.get();
if (Array.isArray(val)) {
return val.map((_, i) => func(this.sub(i as keyof T) as DialogField<ArrayElement<T>>, i));
} else
return [];
}
forEach(func: (val: DialogField<ArrayElement<T>>, index: number) => void): void {
const val = this.get();
if (Array.isArray(val)) {
val.forEach((_, i) => func(this.sub(i as keyof T) as DialogField<ArrayElement<T>>, i));
}
}
remove(index: number) {
const val = this.get();
if (Array.isArray(val)) {
const sub = this.#state.sub.get(index);
if (sub) {
this.#dialog._cancel_debounce(sub);
this.#dialog._abort_state_tasks(sub);
sub.tag = -1;
}
for (let j = index; j < val.length - 1; j++) {
const sub = this.#state.sub.get(j + 1);
if (sub) {
sub.tag = j;
this.#state.sub.set(j, sub);
}
}
this.#state.sub.delete(val.length - 1);
this.#setter(toSpliced(val, index, 1) as T);
this.#trigger();
}
}
add(item: ArrayElement<T>) {
const val = this.get();
if (Array.isArray(val)) {
this.#setter(val.concat(item) as T);
this.#trigger();
}
}
notify(changed_func: (val: T) => void): DialogField<T> {
return new DialogField<T>(
this.#dialog,
this.#state,
this.#getter,
this.#setter,
() => {
changed_func(this.#getter());
this.#trigger();
},
);
}
sub<K extends keyof T>(tag: K, changed_func?: ((val: T[K]) => void) | undefined): DialogField<T[K]> {
const sub = this.#dialog._get_sub_state(this.#state, tag);
const getter = (): T[K] => {
const container = this.get();
if (Array.isArray(container) && typeof sub.tag == "number") {
return container[sub.tag];
} else {
return container[tag];
}
};
const setter = (val: T[K]) => {
const container = this.get();
if (Array.isArray(container) && typeof sub.tag == "number") {
this.#setter(toSpliced(container, sub.tag, 1, val) as T);
} else {
this.#setter({ ...container, [tag]: val });
}
};
const trigger = () => {
if (changed_func)
changed_func(getter());
this.#trigger();
};
return new DialogField<T[K]>(
this.#dialog,
sub,
getter,
setter,
trigger,
);
}
at<TT extends T>(witness: TT): DialogField<TT> {
cockpit.assert(Object.is(witness, this.get()));
return this as unknown as DialogField<TT>;
}
validate(func: (val: T) => DialogValidationResult<T>): void {
const val = this.get();
this.#dialog._validate_value(this.#state, val, () => func(val));
}
validate_async(func: (val: T, signal: AbortSignal) => Promise<DialogValidationResult<T>>): void {
const val = this.get();
this.#dialog._validate_value_async(this.#state, val, signal => func(val, signal));
}
set_async(func: (val: T, signal: AbortSignal) => Promise<T>): void {
const val = this.get();
this.#dialog._set_value_async(this.#state, async signal => {
const new_val = await func(val, signal);
if (!signal.aborted)
this.set(new_val);
});
}
get_async(func: (val: T, signal: AbortSignal) => Promise<void>): void {
const val = this.get();
this.#dialog._get_value_async(this.#state, signal => func(val, signal));
}
}
function get_validation_result_own_string(result: unknown): string | undefined {
if (typeof result == "string")
return result;
else if (result && typeof result == "object" && "" in result && typeof result[""] == "string")
return result[""];
else
return undefined;
}
export class DialogTask {
#name: string;
#promise: Promise<void>;
#controller: AbortController;
constructor(
name: string,
func: (task: DialogTask) => Promise<void>,
done: (task: DialogTask) => void,
) {
debug("starting task", name);
this.#name = name;
this.#controller = new AbortController();
this.#promise = func(this);
this.#promise.finally(() => {
debug("task done", this.#name);
done(this);
});
}
async wait() {
debug("waiting for task", this.#name);
await this.#promise;
}
get_abort_signal() {
return this.#controller.signal;
}
abort() {
debug("aborting task", this.#name);
this.#controller.abort();
}
}
handles, there is at most one of these objects for each field, and
each handle for a given field refers to the exact same
DialogFieldState object.
DialogFieldStates are created on-demand and will over time form a
tree (expressed via "parent" and the children in the "sub" map)
that corresponds to the nesting of the dialog values.
The "tag" is used to access the dialog value. A handle constructed
via dlg.field("name") will point to a state object with tag "name",
for example, and calling handle.get() will return
dlg.values["name"].
Other members of a DialogFieldState relate to validation and
asynchronous updates.
*/
interface DialogFieldState {
parent: DialogFieldState | null,
tag: string | number | symbol;
sub: Map<string | number | symbol, DialogFieldState>;
debounce_timer: number;
debounce_func: null | (() => void);
relevant: boolean;
validation_text: string | undefined;
cached_value: unknown;
cached_result: unknown;
validation_task: DialogTask | null;
update_task: DialogTask | null;
update_tasks: Set<DialogTask>;
}
interface DialogStateEvents {
changed(): void;
}
export class DialogState<V> extends EventEmitter<DialogStateEvents> {
values: V;
busy: boolean = false;
actions_disabled: boolean = false;
cancel_disabled: boolean = false;
error: unknown = null;
#validation_failed: boolean = false;
#online_validation: boolean = false;
#action_running: boolean = false;
#block_updates: boolean = false;
#cancel_function: (() => void) | null = null;
#top_state: DialogFieldState;
#validate_callback: undefined | ((dlg: DialogState<V>) => void);
constructor(init: V, validate: undefined | ((dlg: DialogState<V>) => void)) {
debug("open");
super();
this.#validate_callback = validate;
this.values = init;
this.#top_state = {
parent: null,
tag: "",
sub: new Map(),
debounce_timer: 0,
debounce_func: null,
relevant: false,
validation_text: undefined,
cached_value: undefined,
cached_result: undefined,
validation_task: null,
update_task: null,
update_tasks: new Set(),
};
}
#update() {
this.busy = this.#action_running;
this.actions_disabled = this.#action_running || this.#validation_failed;
this.cancel_disabled = this.#action_running && !this.#cancel_function;
this.emit("changed");
}
During validation and asynchronous updates, a lot is going on.
We use a DialogFieldState object to keep the necessary
state for that, such as cached results, and timeouts and
promises.
These state objects keep their identity when arrays elements
move around. Their "index" field will be changed when that
happens.
*/
_get_sub_state(state: DialogFieldState, tag: string | number | symbol): DialogFieldState {
let sub = state.sub.get(tag);
if (!sub) {
sub = {
parent: state,
tag,
sub: new Map(),
debounce_timer: 0,
debounce_func: null,
relevant: false,
validation_text: undefined,
cached_value: undefined,
cached_result: undefined,
validation_task: null,
update_task: null,
update_tasks: new Set(),
};
state.sub.set(tag, sub);
}
return sub;
}
_for_each_field_state(func: (state: DialogFieldState) => void) {
function visit(state: DialogFieldState) {
func(state);
for (const sub of state.sub.values())
visit(sub);
}
visit(this.#top_state);
}
async _for_each_field_state_async(func: (state: DialogFieldState) => Promise<void>) {
async function visit(state: DialogFieldState) {
await func(state);
for (const sub of state.sub.values())
await visit(sub);
}
await visit(this.#top_state);
}
*/
_cancel_debounce(state: DialogFieldState) {
if (state.debounce_timer) {
debug("cancelling debounce", state_path(state));
window.clearTimeout(state.debounce_timer);
state.debounce_timer = 0;
state.debounce_func = null;
}
for (const sub of state.sub.values())
this._cancel_debounce(sub);
}
_set_debounce(state: DialogFieldState, delay: number, func: () => void) {
if (this.#block_updates)
return;
this._cancel_debounce(state);
if (delay === 0) {
debug("no debounce trigger", state_path(state));
func();
} else {
debug("debounce trigger", state_path(state), delay);
state.debounce_func = func;
state.debounce_timer = window.setTimeout(
() => {
state.debounce_timer = 0;
state.debounce_func = null;
func();
},
delay,
);
}
}
_run_all_debouncing_now() {
let debounced: boolean;
do {
debounced = false;
this._for_each_field_state(state => {
if (state.debounce_timer) {
debug("running debounced trigger now", state_path(state));
cockpit.assert(state.debounce_func);
window.clearTimeout(state.debounce_timer);
state.debounce_timer = 0;
state.debounce_func();
debounced = true;
}
});
} while (debounced);
}
Tasks are a little abstraction that runs a asynchronous
function. Before running the action function, we need to wait
for them all to finish.
*/
async _run_all_tasks_now() {
let awaited: boolean;
do {
this._run_all_debouncing_now();
awaited = false;
await this._for_each_field_state_async(async state => {
if (state.validation_task) {
await state.validation_task.wait();
awaited = true;
}
if (state.update_task) {
await state.update_task.wait();
awaited = true;
}
for (const task of state.update_tasks.values()) {
await task.wait();
awaited = true;
}
});
} while (awaited);
}
_abort_state_tasks(state: DialogFieldState, only_updates: boolean = false) {
debug("cancelling state tasks", state_path(state), only_updates);
if (state.validation_task && !only_updates)
state.validation_task.abort();
if (state.update_task)
state.update_task.abort();
for (const task of state.update_tasks.values())
task.abort();
for (const sub of state.sub.values())
this._abort_state_tasks(sub, only_updates);
}
Validation is started by calling the #trigger_validation
method. This will reset all validation errors and mark all
fields as "irrelevant". Then it calls the provided "validate"
callback, which in turn will (eventually but synchronously)
call the "_validate_value" or "_validate_value_async" methods
of all relevant value paths. Those functions will mark their
fields as relevant and eventually call #set_validation to
install the validation results in the field states.
After this, all irrelevant asynchronous validation tasks are
cancelled.
*/
#validation_needed: boolean = false;
#validation_running: boolean = false;
#trigger_validation(): void {
debug("trigger validation");
if (!this.#validate_callback)
return;
this.#validation_needed = true;
if (this.#validation_running) {
debug("validation postponed");
return;
}
this.#validation_running = true;
while (this.#validation_needed) {
debug("running validation");
this.#validation_needed = false;
this.#validation_failed = false;
this._for_each_field_state(state => {
state.relevant = false;
state.validation_text = undefined;
});
this.#validate_callback(this);
this._for_each_field_state(state => {
if (!state.relevant && state.validation_task) {
debug("aborting irrelevant validation task", state_path(state));
state.validation_task.abort();
}
});
}
this.#validation_running = false;
this.#update();
}
#set_validation(state: DialogFieldState, result: unknown) {
if (result) {
const own = get_validation_result_own_string(result);
if (own) {
state.validation_text = own;
this.#validation_failed = true;
this.#online_validation = true;
}
if (typeof result == "object") {
for (const [k, v] of Object.entries(result)) {
const sub = k && state.sub.get(k);
if (sub)
this.#set_validation(sub, v);
}
}
}
}
value. If the current value is still the same, actual
validation is skipped and the cached result from last time is
used.
Calling #set_validation_state_result is the final thing that
should happen when validating a field. It will install the
result in the cache and then call #set_validation.
*/
#set_validation_state_result(
state: DialogFieldState,
val: unknown,
result: unknown,
) {
state.cached_value = val;
state.cached_result = result;
this.#set_validation(state, result);
}
get a hit, it is used immediately to call #set_validation.
*/
#probe_validation_state_cache(state: DialogFieldState, val: unknown): boolean {
if (Object.is(state.cached_value, val)) {
debug("cache hit", state_path(state), JSON.stringify(val), state.cached_result);
this.#set_validation(state, state.cached_result);
return true;
} else
return false;
}
*/
_validate_value(state: DialogFieldState, val: unknown, func: () => unknown): void {
state.relevant = true;
if (!this.#probe_validation_state_cache(state, val)) {
const result = func();
debug("sync validate", state_path(state), JSON.stringify(result));
this.#set_validation_state_result(state, val, result);
}
}
If there was no cache hit, asynchronous validation starts with
a timeout, followed by letting a asynchronous function run to
resolution. This is managed by a DialogTask.
Starting a new task of course aborts any previous one. It also
installs the current value in the cache, so that subsequent
validation rounds do nothing until the value actually changes.
When the validation result has been computed, we need to check
whether we have been aborted so that we don't install
out-dated results.
*/
_validate_value_async(
state: DialogFieldState,
val: unknown,
func: (signal: AbortSignal) => Promise<unknown>
): void {
state.relevant = true;
if (!this.#probe_validation_state_cache(state, val)) {
state.cached_value = val;
state.cached_result = undefined;
if (state.validation_task)
state.validation_task.abort();
state.validation_task = new DialogTask(
state_path(state) + ":validate",
async task => {
const signal = task.get_abort_signal();
let result;
try {
result = await func(signal);
} catch (ex) {
console.error(ex);
}
if (!signal.aborted) {
debug("async validate result", state_path(state), result);
this.#set_validation_state_result(state, val, result);
this.#update();
}
},
task => {
if (state.validation_task === task)
state.validation_task = null;
}
);
}
}
_set_value_async(
state: DialogFieldState,
func: (signal: AbortSignal) => Promise<void>
): void {
if (state.update_task)
state.update_task.abort();
state.update_task = new DialogTask(
state_path(state) + ":set",
async task => {
try {
await func(task.get_abort_signal());
} catch (ex) {
console.error(ex);
}
},
task => {
if (state.update_task === task)
state.update_task = null;
}
);
}
_get_value_async(
state: DialogFieldState,
func: (signal: AbortSignal) => Promise<void>
): void {
const task = new DialogTask(
state_path(state) + ":get",
async task => {
try {
await func(task.get_abort_signal());
} catch (ex) {
console.error(ex);
}
},
task => {
state.update_tasks.delete(task);
}
);
state.update_tasks.add(task);
}
round and then wait for all the asynchronous results to have
come in.
If there are any DialogFieldState objects that are waiting
for a timeout, we want to abort those and start over, so that
their validation starts immediately. (Also, it would be hairy
to wait for those timeouts to be over from here.)
*/
async validate(): Promise<boolean> {
this.#online_validation = true;
this.#trigger_validation();
await this._run_all_tasks_now();
return !this.#validation_failed;
}
set_cancel(cancel: (() => void) | null) {
this.#cancel_function = cancel;
this.#update();
}
async run_action(func: (vals: V) => Promise<void>): Promise<boolean> {
this.error = null;
this.#cancel_function = null;
this.#action_running = true;
this.#update();
if (!await this.validate()) {
this.#action_running = false;
this.#update();
return false;
}
try {
this.#block_updates = true;
await func(this.values);
} catch (ex) {
console.error(String(ex));
this.error = ex;
}
this.#cancel_function = null;
this.#action_running = false;
this.#block_updates = false;
this.#update();
return !this.error;
}
cancel(onClose: () => void): void {
if (this.#action_running) {
if (this.#cancel_function)
this.#cancel_function();
} else {
this._cancel_debounce(this.#top_state);
this._abort_state_tasks(this.#top_state);
onClose();
}
}
top(changed_func?: ((values: V) => void) | undefined): DialogField<V> {
return new DialogField<V>(
this as DialogState<unknown>,
this.#top_state,
() => this.values,
(val) => {
debug("set", val);
if (this.#block_updates) {
debug("set denied");
return;
}
this.values = val;
this.#update();
},
() => {
if (this.#online_validation)
this.#trigger_validation();
if (changed_func)
changed_func(this.values);
},
);
}
field<K extends keyof V>(tag: K, changed_func?: ((val: V[K]) => void) | undefined): DialogField<V[K]> {
return this.top().sub(tag, changed_func);
}
}
export class DialogError {
title: string;
details: React.ReactNode;
constructor(title: string, details?: React.ReactNode) {
this.title = title;
this.details = details;
}
toString() {
return this.title + ": " + String(this.details);
}
static fromError(title: string, err: unknown) {
if (err && typeof err == "object" && "message" in err && typeof err.message == "string") {
return new DialogError(title, err.message);
} else {
return new DialogError(title, String(err));
}
}
}
export function useDialogState<V extends object>(
init: V | (() => V),
validate?: undefined | ((dlg: DialogState<V>) => void),
) : DialogState<V> {
const dlg = useObject(
() => new DialogState(
typeof init == "function" ? init() : init,
validate
),
null,
[]
);
useOn(dlg, "changed");
return dlg;
}
export function useDialogState_async<V extends object>(
init: () => Promise<V>,
validate?: undefined | ((dlg: DialogState<V>) => void),
) : null | DialogError | DialogState<V> {
const [dlg, setDlg] = useState<null | DialogError | DialogState<V>>(null);
useOn((dlg instanceof DialogError ? null : dlg), "changed");
useInit(async () => {
try {
setDlg(new DialogState<V>(await init(), validate));
} catch (ex) {
if (ex instanceof DialogError)
setDlg(ex);
else
setDlg(DialogError.fromError(_("Error during initialization"), ex));
}
});
return dlg;
}
export function DialogErrorMessage<V>({
dialog,
} : {
dialog: DialogState<V> | DialogError | null,
}) {
const err = (!dialog || dialog instanceof DialogError) ? dialog : dialog.error;
if (!err)
return null;
let title: string;
let details: React.ReactNode;
if (err instanceof DialogError) {
title = err.title;
details = err.details;
} else if (err && typeof err == "object" && "message" in err && typeof err.message == "string") {
title = _("Failed");
details = err.message;
} else {
title = _("Failed");
details = String(err);
}
return (
<Alert
ouiaId="dialog-error-message"
variant='danger'
isInline
title={title}
>
{details}
</Alert>
);
}
export function DialogActionButton<V>({
dialog,
action,
excuse,
onClose = undefined,
isDisabled,
isAriaDisabled,
...props
} : {
dialog: DialogState<V> | DialogError | null,
action: (values: V) => Promise<void>,
excuse?: string | undefined,
onClose?: undefined | (() => void)
} & Omit<ButtonProps, "action">) {
const [running, setRunning] = useState(false);
const btn = (
<Button
ouiaId="dialog-apply"
isLoading={!!dialog && !(dialog instanceof DialogError) && dialog.busy && running}
isDisabled={!dialog || dialog instanceof DialogError || dialog.actions_disabled || !!isDisabled}
isAriaDisabled={!!excuse || !!isAriaDisabled}
onClick={async () => {
cockpit.assert(dialog && !(dialog instanceof DialogError));
setRunning(true);
if (await dialog.run_action(action) && onClose)
onClose();
setRunning(false);
}}
{...props}
/>
);
if (excuse) {
return (
<Tooltip
content={excuse}
>
{btn}
</Tooltip>
);
} else {
return btn;
}
}
export function DialogCancelButton<V>({
dialog,
onClose,
isDisabled,
children,
...props
} : {
dialog: DialogState<V> | DialogError | null,
onClose: () => void
} & ButtonProps) {
return (
<Button
ouiaId="dialog-cancel"
isDisabled={!dialog || (dialog instanceof DialogState && dialog.cancel_disabled) || !!isDisabled}
variant="link"
onClick={() => {
if (dialog instanceof DialogState)
dialog.cancel(onClose);
else
onClose();
}}
{...props}
>
{children || _("Cancel")}
</Button>
);
}
*/
type falsy = null | undefined | false;
export function DialogHelperText<V>({
field,
excuse,
warning,
explanation,
} : {
field: DialogField<V>;
excuse?: string | falsy;
warning?: React.ReactNode;
explanation?: React.ReactNode;
}) {
let text: React.ReactNode = field.validation_text();
let variant: HelperTextItemProps["variant"] = "error";
if (!text && excuse) {
text = excuse;
variant = "default";
}
if (!text && warning) {
text = warning;
variant = "warning";
}
if (!text) {
text = explanation;
variant = "default";
}
if (!text)
return null;
return (
<FormHelperText>
<HelperText>
<HelperTextItem data-ouia-component-id={field.ouia_id("helper-text")} variant={variant}>
{text}
</HelperTextItem>
</HelperText>
</FormHelperText>
);
}
into a FormGroup. In that case, the <label> produced by the
FormGroup and the actual input element should be connected via
"for" and "id" attributes, for a11y reasons.
But a porcelain wrapper can also be used without an automatic
FormGroup. In that case the user has to provide an explicit id for
making that connection or maybe an aria-label.
The useFormId hook helps with that.
*/
function useFormId(id: string | undefined, label: React.ReactNode) {
const random_id = useId();
return id || (label ? random_id : undefined);
}
export const OptionalFormGroup = ({
label,
children,
fieldId,
...props
} : {
label: React.ReactNode,
children: React.ReactNode,
fieldId?: string | undefined,
} & Omit<FormGroupProps, "fieldId" | "label" | "children">) => {
if (label) {
return (
<FormGroup
label={label}
{...fieldId ? { fieldId } : {} }
{...props}
>
{children}
</FormGroup>
);
} else {
return children;
}
};
export const DialogTextInput = ({
label = null,
field,
debounce,
excuse,
warning,
explanation,
isDisabled = false,
id,
...props
} : {
label?: React.ReactNode,
field: DialogField<string>,
debounce?: number | undefined,
excuse?: string | falsy,
warning?: React.ReactNode,
explanation?: React.ReactNode,
isDisabled?: boolean,
} & Omit<TextInputProps, "label" | "value" | "onChange">) => {
const fid = useFormId(id, label);
return (
<OptionalFormGroup label={label} fieldId={fid}>
<TextInput
id={fid}
ouiaId={field.ouia_id()}
value={field.get()}
onChange={(_event, val) => field.set_debounced(val, debounce)}
isDisabled={!!excuse || isDisabled}
{...props}
/>
<DialogHelperText explanation={explanation} warning={warning} excuse={excuse} field={field} />
</OptionalFormGroup>
);
};
export const DialogPasswordInput = ({
label = null,
field,
debounce,
excuse,
warning,
explanation,
isDisabled = false,
id,
...props
} : {
label?: React.ReactNode,
field: DialogField<string>,
debounce?: number | undefined,
excuse?: string | falsy,
warning?: React.ReactNode,
explanation?: React.ReactNode,
isDisabled?: boolean,
} & Omit<TextInputProps, "label" | "value" | "onChange">) => {
const [visible, setVisible] = useState(false);
const fid = useFormId(id, label);
return (
<OptionalFormGroup label={label} fieldId={fid}>
<InputGroup>
<InputGroupItem isFill>
<TextInput
id={fid}
ouiaId={field.ouia_id()}
type={visible ? "text" : "password"}
value={field.get()}
onChange={(_event, value) => field.set_debounced(value, debounce)}
isDisabled={!!excuse || isDisabled}
{...props}
/>
</InputGroupItem>
<InputGroupItem>
<Button
variant="control"
aria-label={visible ? _("Hide password") : _("Show password")}
onClick={() => setVisible(!visible)}
>
{visible ? <EyeSlashIcon /> : <EyeIcon />}
</Button>
</InputGroupItem>
</InputGroup>
<DialogHelperText explanation={explanation} warning={warning} excuse={excuse} field={field} />
</OptionalFormGroup>
);
};
export const DialogCheckbox = ({
field_label = null,
checkbox_label,
field,
excuse,
warning,
explanation,
} : {
field_label?: React.ReactNode,
checkbox_label: string,
field: DialogField<boolean>,
excuse?: string | falsy,
warning?: React.ReactNode,
explanation?: React.ReactNode,
}) => {
const id = useId();
return (
<OptionalFormGroup label={field_label} hasNoPaddingTop>
<Checkbox
id={id}
ouiaId={field.ouia_id()}
isChecked={field.get()}
label={checkbox_label}
onChange={(_event, checked) => field.set(checked)}
isDisabled={!!excuse}
/>
<DialogHelperText explanation={explanation} warning={warning} excuse={excuse} field={field} />
</OptionalFormGroup>
);
};
export interface DialogRadioSelectOption<T extends string> {
value: T,
label: React.ReactNode,
explanation?: React.ReactNode,
excuse?: string | falsy,
}
export function DialogRadioSelect<T extends string>({
label = null,
field,
options,
warning,
explanation,
isInline = false,
} : {
label?: React.ReactNode,
field: DialogField<T>,
options: DialogRadioSelectOption<T>[],
warning?: React.ReactNode,
explanation?: React.ReactNode,
isInline?: boolean,
}) {
const random_id = useId();
function makeLabel(o: DialogRadioSelectOption<T>, i: number) {
const exc = o.excuse ? <> ({o.excuse})</> : null;
const pad = (!isInline && i < options.length - 1) ? <><br />{"\u00A0"}</> : null;
const exp = o.explanation ? <><br /><small>{o.explanation}{pad}</small></> : null;
return <div data-ouia-component-id={field.ouia_id(o.value + "-label")}>{o.label}{exc}{exp}</div>;
}
return (
<OptionalFormGroup
label={label}
hasNoPaddingTop
isInline={isInline}
ouiaId={field.ouia_id()}
data-value={field.get()}
>
{
options.map((o, i) =>
<Radio
key={o.value}
id={random_id + o.value}
ouiaId={field.ouia_id(o.value)}
name={o.value}
isChecked={field.get() === o.value}
label={makeLabel(o, i)}
onChange={() => field.set(o.value)}
isDisabled={!!o.excuse}
/>
)
}
<DialogHelperText explanation={explanation} warning={warning} field={field} />
</OptionalFormGroup>
);
}
export interface DialogDropdownSelectOption<T extends string> {
value: T;
label: string;
}
export function DialogDropdownSelect<T extends string>({
label,
field,
excuse,
warning,
explanation,
options,
id,
...props
} : {
label?: React.ReactNode,
field: DialogField<T>,
excuse?: string | falsy,
warning?: React.ReactNode,
explanation?: React.ReactNode,
options: DialogDropdownSelectOption<T>[],
} & Omit<FormSelectProps, "ref" | "children">) {
const fid = useFormId(id, label);
return (
<OptionalFormGroup label={label} fieldId={fid}>
<FormSelect
id={fid}
ouiaId={field.ouia_id()}
onChange={(_event, val) => field.set(val as T) }
validated={warning ? "warning" : undefined}
isDisabled={!!excuse}
value={field.get()}
{...props}
>
{
options.map(
o => {
return <FormSelectOption key={o.value} value={o.value} label={o.label} />;
}
)
}
</FormSelect>
<DialogHelperText explanation={explanation} warning={warning} excuse={excuse} field={field} />
</OptionalFormGroup>
);
}
export function DialogDropdownSelectObject<T>({
label,
field,
excuse,
warning,
explanation,
options,
option_label = (o: T): string => { cockpit.assert(typeof o == "string"); return o },
id,
...props
} : {
label?: React.ReactNode,
field: DialogField<T>,
excuse?: string | falsy,
warning?: React.ReactNode,
explanation?: React.ReactNode,
options: T[],
option_label?: (o: T) => string,
} & Omit<FormSelectProps, "ref" | "children">) {
const fid = useFormId(id, label);
return (
<OptionalFormGroup label={label} fieldId={fid}>
<FormSelect
id={fid}
ouiaId={field.ouia_id()}
onChange={(_event, val) => {
const opt = options.find(o => option_label(o) === val);
field.set(opt!);
}}
validated={warning ? "warning" : undefined}
isDisabled={!!excuse}
value={option_label(field.get())}
{...props}
>
{
options.map(
o => {
const l = option_label(o);
return <FormSelectOption key={l} value={l} label={l} />;
}
)
}
</FormSelect>
<DialogHelperText explanation={explanation} warning={warning} excuse={excuse} field={field} />
</OptionalFormGroup>
);
}
