Published foldkit-ui API declarations for radioGroup.
./radioGroup
@wsagency/wseffect-foldkit-ui · MIT · source · MIT license · WS-AGENCY-NOTICE · THIRD-PARTY-NOTICES
This entry point is published in @wsagency/wseffect-foldkit-ui@0.1.0-rc.1. Import it from the package subpath shown below; the signatures and documentation are read from the installed package declarations.
import * as Wseffect from '@wsagency/wseffect-foldkit-ui/radioGroup'
Exported declarations
Bundle
The `view` and `update` pair that `RadioGroup.create` returns, bound to one
`Value` type. Name it to annotate a value that holds a created bundle,
such as a field on a config object or a function parameter that takes
the bundle rather than calling `create` itself.
export type Bundle<Value extends string = string> = Readonly<{
view: SubmodelView<Model, Message, ViewInputs<Value>>;
update: (model: Model, message: Message) => Update.ReturnWithOutMessage<Model, Message, OutMessage<Value>>;
}>;
create
Pairs the radio group `view` and `update` behind a single Value-typed
entry point. Declare once at module scope so consumers receive
`option.value: Value` in `toView` and the `Selected` OutMessage without an
`as` cast:
```ts
const PlanRadioGroup = RadioGroup.create<Plan>()
// In view (selectedValue is the parent-owned selection):
h.submodel({ view: PlanRadioGroup.view, viewInputs: { selectedValue, ... }, ... })
// In the parent update, pass PlanRadioGroup.update to Update.foldChild
// and fold the Selected OutMessage into your Model.
```
The internal view stays typed `ReadonlyArray<string>`; consumers can
pass a `ReadonlyArray<MyUnion>` (assignable) and the fenced cast inside
`create` types `OptionInfo.value` as `MyUnion`.
create: <Value extends string = string>() => Bundle<Value>
FocusedOption
export type FocusedOption = typeof Message.FocusedOption.Type;
FocusOption
Moves focus to the option at the given index.
FocusOption: Command.CommandDefinitionWithArgs<"FocusOption", {
id: Schema.String;
index: Schema.Number;
}, Effect.Effect<{
readonly _tag: "CompletedFocusOption";
}, never, never>>
init
Creates an initial radio group model from a config. Focus follows the
selected option until the user navigates a read-only group, so
`maybeFocusedIndex` starts `None`.
init: (config: InitConfig) => Model
InitConfig
Configuration for creating a radio group model with `init`.
export type InitConfig = Readonly<{
id: string;
}>;
Message
export type Message = typeof Message.Type;
Message
Union of all messages the radio group can produce.
Message: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
readonly SelectedOption: {
index: Schema.Number;
value: Schema.String;
};
readonly FocusedOption: {
index: Schema.Number;
};
readonly CompletedFocusOption: {};
}>
Model
export type Model = typeof Model.Type;
Model
Schema for the radio group's private interaction state. The selected
option is owned by the parent and passed in via `ViewInputs.selectedValue`,
so it is not stored here. `maybeFocusedIndex` is the roving-tabindex
cursor: `None` means keyboard focus follows the selection, and a read-only
group stores `Some(index)` while focus diverges from it.
Model: Schema.Struct<{
readonly id: Schema.String;
readonly maybeFocusedIndex: Schema.Option<Schema.Number>;
}>
OptionInfo
Per-option render info passed to the consumer's `toView`. The consumer
spreads `option`, `label`, and `description` onto whichever elements carry
that role in their layout. Generic over `Value extends string` so
`option.value` carries the consumer's union type.
The `option` bundle sets `type="button"` so that rendering the option as a
`button` element inside a `form` element selects without also submitting the
form. Setting it is harmless on the other elements an option might use, such
as a `div` or a `span`, because the builder assigns a DOM property rather
than an HTML attribute. Spread a later `h.Type` to override it.
export type OptionInfo<Value extends string = string> = Readonly<{
value: Value;
index: number;
isSelected: boolean;
isActive: boolean;
isDisabled: boolean;
isReadOnly: boolean;
option: ReadonlyArray<ChildAttribute>;
label: ReadonlyArray<ChildAttribute>;
description: ReadonlyArray<ChildAttribute>;
}>;
Orientation
export type Orientation = typeof Orientation.Type;
Orientation
Controls the radio group layout direction and which arrow keys navigate between options.
Orientation: Schema.Literals<readonly ["Horizontal", "Vertical"]>
OutMessage
Generic over `Value extends string` so consumers using
`RadioGroup.create<MyUnion>()` receive `value: MyUnion` in the
`Selected` OutMessage. Defaults to `string`.
export type OutMessage<Value extends string = string> = Selected<Value>;
OutMessage
Union of OutMessages the radio group can produce. The parent's
`Update.foldChild` config handles them through `foldOutMessage`.
OutMessage: import("@wsagency/wseffect-foldkit/message").MessageUnion<{
readonly Selected: {
value: Schema.String;
index: Schema.Number;
};
}>
RenderInfo
Render-time payload published to the consumer's `toView`.
- `group`: ARIA + role attributes for the wrapping radiogroup element.
- `options`: one entry per option in `viewInputs.options`, in the same
order. Includes the value, derived state, and the attribute bundles for
the option element, its label, and its description.
- `selectedValue`: the currently-selected value, if any. Convenient for the
consumer when rendering selected-state visuals next to the option
attributes.
- `hiddenInput`: when `name` was supplied, attributes for a hidden form
input carrying the selected value. The consumer renders the `<input>`
themselves. Empty array when `name` is undefined.
export type RenderInfo<Value extends string = string> = Readonly<{
group: ReadonlyArray<ChildAttribute>;
options: ReadonlyArray<OptionInfo<Value>>;
selectedValue: Option.Option<Value>;
hiddenInput: ReadonlyArray<ChildAttribute>;
}>;
Selected
export type Selected<Value extends string = string> = Readonly<{
readonly _tag: 'Selected';
readonly value: Value;
readonly index: number;
}>;
SelectedOption
export type SelectedOption = typeof Message.SelectedOption.Type;
ViewInputs
Per-render view inputs passed to `view` via `h.submodel`'s `viewInputs`
field. Generic over `Value extends string` so consumers using
`RadioGroup.create<MyUnion>()` receive `option.value: MyUnion` in `toView`
and `(value: MyUnion, index) => boolean` in `isOptionDisabled`, without
casting.
- `selectedValue`: the current selection, read straight from the parent
Model. `aria-checked` and the `data-checked` marker derive from it, as
does the roving tabindex whenever keyboard focus has not diverged.
- `isReadOnly`: keeps the group navigable but not selectable. Arrow, Home,
End, PageUp, and PageDown still move focus, and the group reports that
focus through `FocusedOption`, so `data-active` and `tabindex` follow it.
Space and clicking do nothing.
export type ViewInputs<Value extends string = string> = Readonly<{
options: ReadonlyArray<Value>;
selectedValue: Option.Option<Value>;
ariaLabel: string;
toView: (render: RenderInfo<Value>) => Html;
orientation?: Orientation;
isOptionDisabled?: (value: Value, index: number) => boolean;
hasOptionDescription?: (value: Value, index: number) => boolean;
isDisabled?: boolean;
isReadOnly?: boolean;
name?: string;
}>;