Sprites.Optional
Helpers for values that may be absent. Default reads an optional value and falls back to a default when it is missing, so a caller reads one value that is always present. Present and Absent build content while a value is present or missing, the two mirrors of one another. Every argument is a constant or a reactive value, so the result stays live.
Sprites.Optional.Default Sprites.Reactive.Value
Sprites.Optional.Default(optionalValue, defaultValue)
The optional value when it is present, else the default. A value is present when it is anything other than undefined, so zero and the empty string stand as given. Either argument may be a constant or a reactive value, so the result follows both.
| Input | Type | Description |
|---|---|---|
optionalValue | Any or Sprites.Reactive.Value | The value that may be missing. |
defaultValue | Any or Sprites.Reactive.Value | The fallback used while the value is missing. |
Returns a read-only Sprites.Reactive.Value, the optional value while it is present and the default while it is missing.
const provided = Sprites.Reactive.Value(false);
const width = Sprites.Logic.Select(provided, 8, undefined);
const size = Sprites.Optional.Default(width, 32);
Sprites.Ui.Input.Checkbox(provided);
Sprites.Ui.Dom.Text(' size = ', size);Sprites.Optional.Present build
Sprites.Optional.Present(optionalValue, build)
Build the content while the optional value is present, and remove it while the value is missing. A value is present when it is anything other than undefined, so zero and the empty string count as present. Build receives a read-only reactive value that follows the optional value, so the content stays live while it is shown. This is the mirror of Absent.
| Input | Type | Description |
|---|---|---|
optionalValue | Any or Sprites.Reactive.Value | The value that may be missing. |
build | Function | Called with the present value to build the content shown while it is present. |
Returns nothing; it places content in the current build.
const provided = Sprites.Reactive.Value(false);
const width = Sprites.Logic.Select(provided, 8, undefined);
Sprites.Ui.Input.Checkbox(provided);
Sprites.Optional.Present(width, (value) => {
Sprites.Ui.Dom.Text(' width = ', value);
});Sprites.Optional.Absent build
Sprites.Optional.Absent(optionalValue, build)
Build the content while the optional value is missing, and remove it once a value arrives. A value is missing when it is undefined. Build is called with no arguments, since there is no value to show. This is the mirror of Present.
| Input | Type | Description |
|---|---|---|
optionalValue | Any or Sprites.Reactive.Value | The value that may be missing. |
build | Function | Called with no arguments to build the content shown while the value is missing. |
Returns nothing; it places content in the current build.
const provided = Sprites.Reactive.Value(false);
const width = Sprites.Logic.Select(provided, 8, undefined);
Sprites.Ui.Input.Checkbox(provided);
Sprites.Optional.Absent(width, () => {
Sprites.Ui.Dom.Text(' no width yet');
});Sprites.Optional.If Sprites.Reactive.Value
Sprites.Optional.If(optionalValue, whenPresent)
The value whenPresent builds from the optional value while it is present, else undefined while it is absent. It is the value form of Present, running whenPresent only while the value is there, so the work it builds is made and torn down with the value and never runs over an absent one. Where Default chooses between two ready values, this chooses whether to build a value at all, so a whole shape follows an optional and returns to undefined when it is not there.
| Input | Type | Description |
|---|---|---|
optionalValue | Any or Sprites.Reactive.Value | The value that may be missing. |
whenPresent | Function | Called with the optional value while it is present, returning the value to collect. |
Returns a read-only Sprites.Reactive.Value, whenPresent's result while the value is present and undefined while it is absent.
const provided = Sprites.Reactive.Value(false);
const width = Sprites.Logic.Select(provided, 8, undefined);
const doubled = Sprites.Optional.If(width, (value) => {
return Sprites.Maths.Add(value, value);
});
const shown = Sprites.Optional.Default(doubled, 'nothing');
Sprites.Ui.Input.Checkbox(provided);
Sprites.Ui.Dom.Text(' doubled = ', shown);