# `Toddy.Iced.A11y`
[🔗](https://github.com/toddy-ui/toddy-elixir/blob/v0.3.0/lib/toddy/iced/a11y.ex#L1)

Accessibility annotation type for widget nodes.

When attached to a widget via the `a11y` prop, these attributes override the
auto-inferred accessibility semantics on the renderer side. The renderer
automatically derives roles and labels from widget types and props (e.g. a
button's label becomes the accessible name), so most widgets need no explicit
`a11y` annotation. Use this for cases where auto-inference is insufficient.

Use `cast/1` to normalize a bare map into an `A11y` struct. Bare maps with
atom keys are accepted for convenience.

## Fields

- `role` -- overrides the inferred accesskit role (e.g. `:heading`, `:alert`)
- `label` -- accessible name announced by screen readers
- `description` -- longer description (maps to accesskit description)
- `live` -- live region semantics: `:polite` or `:assertive`
- `hidden` -- if true, node is excluded from the accessibility tree
- `expanded` -- expanded/collapsed state for disclosure widgets
- `required` -- marks a form field as required
- `level` -- heading level (1-6)
- `busy` -- loading/processing state
- `invalid` -- form validation failure
- `modal` -- dialog is modal
- `read_only` -- can be read but not edited
- `mnemonic` -- Alt+letter keyboard shortcut (single character)
- `toggled` -- toggled/checked state (for custom toggle widgets)
- `selected` -- selected state (for custom selectable widgets)
- `value` -- current value as a string (for custom value-displaying widgets)
- `orientation` -- `:horizontal` or `:vertical` (for custom oriented widgets)
- `labelled_by` -- ID of the widget that labels this one
- `described_by` -- ID of the widget that describes this one
- `error_message` -- ID of the widget showing the error message for this one

# `live`

```elixir
@type live() :: :polite | :assertive
```

# `orientation`

```elixir
@type orientation() :: :horizontal | :vertical
```

# `role`

```elixir
@type role() ::
  :window
  | :tree_item
  | :tree
  | :tooltip
  | :toolbar
  | :text_input
  | :table
  | :tab_panel
  | :tab_list
  | :tab
  | :switch
  | :status
  | :static_text
  | :slider
  | :separator
  | :search
  | :scroll_view
  | :scroll_bar
  | :region
  | :radio_button
  | :progress_indicator
  | :navigation
  | :multiline_text_input
  | :meter
  | :menu_item
  | :menu_bar
  | :menu
  | :list_item
  | :list
  | :link
  | :label
  | :image
  | :heading
  | :group
  | :generic_container
  | :document
  | :dialog
  | :combo_box
  | :check_box
  | :canvas
  | :button
  | :alert_dialog
  | :alert
```

# `t`

```elixir
@type t() :: %Toddy.Iced.A11y{
  busy: boolean() | nil,
  described_by: String.t() | nil,
  description: String.t() | nil,
  error_message: String.t() | nil,
  expanded: boolean() | nil,
  hidden: boolean() | nil,
  invalid: boolean() | nil,
  label: String.t() | nil,
  labelled_by: String.t() | nil,
  level: pos_integer() | nil,
  live: live() | nil,
  mnemonic: String.t() | nil,
  modal: boolean() | nil,
  orientation: orientation() | nil,
  read_only: boolean() | nil,
  required: boolean() | nil,
  role: role() | nil,
  selected: boolean() | nil,
  toggled: boolean() | nil,
  value: String.t() | nil
}
```

# `cast`

```elixir
@spec cast(a11y :: t() | map()) :: t()
```

Normalizes a struct or bare map into an `A11y` struct.

Accepts an `A11y` struct (returned as-is) or a bare map with atom keys.
Unknown keys are silently ignored.

## Examples

    iex> Toddy.Iced.A11y.cast(%{role: :heading, level: 1})
    %Toddy.Iced.A11y{role: :heading, level: 1}

    iex> a11y = %Toddy.Iced.A11y{label: "Close"}
    iex> Toddy.Iced.A11y.cast(a11y)
    %Toddy.Iced.A11y{label: "Close"}

---

*Consult [api-reference.md](api-reference.md) for complete listing*