Skip to main content
On this pageFunctions

Ui/RadioGroup

Functions

create

functionsource
/**
 * Creates a completed RadioGroup Block refined to one Value type. Declare
 * `RadioGroup.create<Plan>()` once at module scope, then connect that Block to
 * the parent. Its view inputs and `Selected.value` share the Value type;
 * the parent Model owns the selected option.
 */
<Value extends string = string>(): Completed<Value>

Types

InitConfig

typesource
/** Configuration for creating a radio group model with `init`. */
type InitConfig = Readonly<{
  id: string
}>

OptionInfo

typesource
/**
 * 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.
 */
type OptionInfo = Readonly<{
  description: ReadonlyArray<ChildAttribute>
  index: number
  isActive: boolean
  isDisabled: boolean
  isReadOnly: boolean
  isSelected: boolean
  label: ReadonlyArray<ChildAttribute>
  option: ReadonlyArray<ChildAttribute>
  value: Value
}>

RenderInfo

typesource
/**
 * 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.
 */
type RenderInfo = Readonly<{
  group: ReadonlyArray<ChildAttribute>
  hiddenInput: ReadonlyArray<ChildAttribute>
  options: ReadonlyArray<OptionInfo<Value>>
  selectedValue: Option.Option<Value>
}>

ViewInputs

typesource
/**
 * Per-render view inputs passed to `view` via `h.block`'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.
 */
type ViewInputs = Readonly<{
  ariaLabel: string
  hasOptionDescription: (value: Value, index: number) => boolean
  isDisabled: boolean
  isOptionDisabled: (value: Value, index: number) => boolean
  isReadOnly: boolean
  name: string
  options: ReadonlyArray<Value>
  orientation: Orientation
  selectedValue: Option.Option<Value>
  toView: (render: RenderInfo<Value>) => Html
}>

Interfaces

Completed

interfacesource
/** A completed RadioGroup Block refined to one Value type. */
interface Completed {
  [CompletionTypeId]: true
  [DefaultViewTypeId]: OwnedAuthoredView<BlockView<{
    id: string
    maybeFocusedIndex: Option<number>
  }, {
    _tag: "SelectedOption"
    index: number
    value: string
  } | {
    _tag: "FocusedOption"
    index: number
  } | {
    _tag: "CompletedFocusOption"
  }, AuthoredViewInputs<Readonly<{
    ariaLabel: string
    hasOptionDescription: (value: Value, index: number) => boolean
    isDisabled: boolean
    isOptionDisabled: (value: Value, index: number) => boolean
    isReadOnly: boolean
    name: string
    options: readonly Array<Value>
    orientation: "Horizontal" | "Vertical"
    selectedValue: Option<Value>
    toView: (render: RenderInfo<Value>) => Html
  }>>, never>, Owner<"RadioGroup", true>, {
    id: string
    maybeFocusedIndex: Option<number>
  }, {
    _tag: "SelectedOption"
    index: number
    value: string
  } | {
    _tag: "FocusedOption"
    index: number
  } | {
    _tag: "CompletedFocusOption"
  }, never>
  bindings: readonly []
  EffectsLayer: CompleteEffectsLayer<Layer<Handler<"RadioGroup/FocusOption", {
    id: string
    index: number
  }, {
    _tag: "CompletedFocusOption"
  }>, never, never>, readonly []>
  hostHandlers: readonly []
  init: (args: [
    config: Readonly<{
      id: string
    }>
  ]) => Return<{
    id: string
    maybeFocusedIndex: Option<number>
  }, {
    _tag: "SelectedOption"
    index: number
    value: string
  } | {
    _tag: "FocusedOption"
    index: number
  } | {
    _tag: "CompletedFocusOption"
  }, never>
  makeView: DefineView<Owner<"RadioGroup", true>, {
    id: string
    maybeFocusedIndex: Option<number>
  }, {
    _tag: "SelectedOption"
    index: number
    value: string
  } | {
    _tag: "FocusedOption"
    index: number
  } | {
    _tag: "CompletedFocusOption"
  }, never>
  managedResources: Readonly<Record<never, never>>
  Message: MessageUnion
  Model: Struct
  mounts: readonly Array<never>
  operations: ImplementationExposedOperations<ImplementationValue>
  OutMessage: MessageUnion
  provideHandlers: never
  replaceEffectsLayer: ReplaceEffectsLayer<Owner<"RadioGroup", true>, Struct<{
    id: String
    maybeFocusedIndex: Option<Number>
  }>, MessageUnion<{
    CompletedFocusOption: {}
    FocusedOption: {
      index: Number
    }
    SelectedOption: {
      index: Number
      value: String
    }
  }>, MessageUnion<Omit<{
    Selected: {
      index: Number
      value: String
    }
  }, "Selected"> & Readonly<{
    Selected: Omit<{
      index: Number
      value: String
    }, "value"> & Readonly<{
      value: Schema<Value>
    }>
  }>>, readonly [], readonly [], Readonly<{
    EffectsLayer: Layer<Handler<"RadioGroup/FocusOption", {
      id: string
      index: number
    }, {
      _tag: "CompletedFocusOption"
    }>, never, never>
    init: (args: [
      config: Readonly<{
        id: string
      }>
    ]) => Return<{
      id: string
      maybeFocusedIndex: Option<number>
    }, {
      _tag: "SelectedOption"
      index: number
      value: string
    } | {
      _tag: "FocusedOption"
      index: number
    } | {
      _tag: "CompletedFocusOption"
    }, never>
    update: (message: {
      _tag: "SelectedOption"
      index: number
      value: string
    } | {
      _tag: "FocusedOption"
      index: number
    } | {
      _tag: "CompletedFocusOption"
    }) => (model: {
      id: string
      maybeFocusedIndex: Option<number>
    }, context: readonly []) => ReturnWithOutMessage<{
      id: string
      maybeFocusedIndex: Option<number>
    }, {
      _tag: "SelectedOption"
      index: number
      value: string
    } | {
      _tag: "FocusedOption"
      index: number
    } | {
      _tag: "CompletedFocusOption"
    }, Readonly<{
      _tag: "Selected"
      index: number
      value: Value
    }>, Handler<"RadioGroup/FocusOption", {
      id: string
      index: number
    }, {
      _tag: "CompletedFocusOption"
    }>>
    view: OwnedAuthoredView<BlockView<{
      id: string
      maybeFocusedIndex: Option<number>
    }, {
      _tag: "SelectedOption"
      index: number
      value: string
    } | {
      _tag: "FocusedOption"
      index: number
    } | {
      _tag: "CompletedFocusOption"
    }, AuthoredViewInputs<Readonly<{
      ariaLabel: string
      hasOptionDescription: (value: Value, index: number) => boolean
      isDisabled: boolean
      isOptionDisabled: (value: Value, index: number) => boolean
      isReadOnly: boolean
      name: string
      options: readonly Array<Value>
      orientation: "Horizontal" | "Vertical"
      selectedValue: Option<Value>
      toView: (render: RenderInfo<Value>) => Html
    }>>, never>, Owner<"RadioGroup", true>, {
      id: string
      maybeFocusedIndex: Option<number>
    }, {
      _tag: "SelectedOption"
      index: number
      value: string
    } | {
      _tag: "FocusedOption"
      index: number
    } | {
      _tag: "CompletedFocusOption"
    }, never>
  }>>
  subscriptions: Readonly<Record<never, never>>
  update: (message: {
    _tag: "SelectedOption"
    index: number
    value: string
  } | {
    _tag: "FocusedOption"
    index: number
  } | {
    _tag: "CompletedFocusOption"
  }) => (model: {
    id: string
    maybeFocusedIndex: Option<number>
  }, context: readonly []) => ReturnWithOutMessage<{
    id: string
    maybeFocusedIndex: Option<number>
  }, {
    _tag: "SelectedOption"
    index: number
    value: string
  } | {
    _tag: "FocusedOption"
    index: number
  } | {
    _tag: "CompletedFocusOption"
  }, Readonly<{
    _tag: "Selected"
    index: number
    value: Value
  }>, Handler<"RadioGroup/FocusOption", {
    id: string
    index: number
  }, {
    _tag: "CompletedFocusOption"
  }>>
}

Constants

Orientation

constsource
/** Controls the radio group layout direction and which arrow keys navigate between options. */
const Orientation: Literals<readonly ["Horizontal", "Vertical"]>