Documentation navigation

Published API · 0.1.0-rc.1

foldkit-ui · radioGroup

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;
}>;