# `Dala.Ui.Widgets`
[🔗](https://github.com/manhvu/dala/blob/main/lib/dala/ui/widgets.ex#L1)

UI component constructors for the Dala framework.

Each function returns a node map compatible with `Dala.Ui.Renderer`. These can
be used directly or mixed freely — they produce the same map format.

    # Native map literal
    %{type: :text, props: %{text: "Hello"}, children: []}

    # Component function (keyword list or map)
    Dala.Ui.Widgets.text(text: "Hello")

Both forms produce identical output and are accepted by `Dala.Ui.Renderer`.

# `activity_indicator`

```elixir
@spec activity_indicator(keyword() | map()) :: map()
```

Returns an `:activity_indicator` leaf node. Displays a circular loading spinner.

## Props

  * `:size` — `:small` or `:large` (default: `:small`)
  * `:color` — spinner color (default: theme primary)
  * `:animating` — whether spinner is animating (default: true)

# `app_bar`

```elixir
@spec app_bar(keyword() | map()) :: map()
```

Returns a `:app_bar` leaf node. A top app bar with title and action icons.

## Props

  * `:title` — string, app bar title
  * `:leading_icon` — string, icon name for the leading navigation icon
  * `:on_leading` — `{pid, tag}` tuple; fired when leading icon is tapped
  * `:trailing_actions` — list of maps with `:icon` and `:on_tap`
  * `:background` — background color
  * `:text_color` — title and icon color
  * `:accessibility_id` — test identifier

## Examples

    Dala.Ui.Widgets.app_bar(
      title: "My App",
      leading_icon: "back",
      on_leading: {self(), :back_pressed},
      trailing_actions: [%{icon: "search", on_tap: {self(), :search}}]
    )

# `badge`

```elixir
@spec badge(keyword() | map(), list()) :: map()
```

Returns a `:badge` container node. Displays a numeric badge over its children.

## Props

  * `:count` — integer, numeric badge value
  * `:color` — badge background color
  * `:text_color` — badge text color
  * `:visible` — boolean, whether the badge is shown (default: true)

## Examples

    Dala.Ui.Widgets.badge([count: 5, color: :error], [
      Dala.Ui.Widgets.icon(name: "notifications")
    ])

# `bottom_sheet`

```elixir
@spec bottom_sheet(keyword() | map(), list()) :: map()
```

Returns a `:bottom_sheet` container node. A slide-up panel anchored to the bottom.

## Props

  * `:visible` — boolean, whether the sheet is shown
  * `:on_dismiss` — `{pid, tag}` tuple; fired when the sheet is dismissed
  * `:drag_indicator` — boolean, show drag handle at top (default: true)
  * `:peek_height` — float, height of the sheet when partially visible
  * `:background` — background color
  * `:corner_radius` — rounded corners at the top

## Examples

    Dala.Ui.Widgets.bottom_sheet([visible: true, on_dismiss: {self(), :dismissed}, drag_indicator: true], [
      Dala.Ui.Widgets.text(text: "Sheet content")
    ])

# `box`

```elixir
@spec box(keyword() | map(), list()) :: map()
```

Returns a `:box` container node. Children are stacked on top of each other (ZStack).

Same props as `column/2`. Useful for overlays, badges, and absolute positioning.

# `button`

```elixir
@spec button(keyword() | map()) :: map()
```

Returns a `:button` leaf node.

## Props

  * `:text` — button label (required). Also accepts `:title` for backward compatibility.
  * `:on_tap` — `{pid, tag}` tuple; fired when button is pressed
  * `:disabled` — boolean, disables the button (default: false)
  * `:text_color` — label color (accepts color tokens)
  * `:text_size` — font size
  * `:font_weight` — `"regular"`, `"medium"`, `"semibold"`, `"bold"`, `"light"`, `"thin"`
  * `:background` — button background color (accepts color tokens)
  * `:padding`, `:padding_top`, `:padding_right`, `:padding_bottom`, `:padding_left`
  * `:corner_radius` — rounded corners
  * `:fill_width` — boolean, stretch to fill parent width (default: true from component defaults)
  * `:accessibility_id` — test identifier

## Examples

    Dala.Ui.Widgets.button(text: "Submit", on_tap: {self(), :submit})
    Dala.Ui.Widgets.button(title: "OK", on_tap: {self(), :ok}, background: :primary)

# `camera_preview`

```elixir
@spec camera_preview(keyword() | map()) :: map()
```

Returns a `:camera_preview` component node. Renders a live camera feed inline.

Call `Dala.Media.Camera.start_preview/2` before mounting this component, and
`Dala.Media.Camera.stop_preview/1` when done.

## Props

  * `:facing` — `:back` (default) or `:front`
  * `:width`, `:height` — dimensions in dp/pts; omit to fill parent

# `card`

```elixir
@spec card(keyword() | map(), list()) :: map()
```

Returns a `:card` container node. A Material-style card with elevation and variants.

## Props

  * `:elevation` — float, shadow depth
  * `:variant` — `:filled`, `:outlined`, or `:elevated`
  * `:background` — background color
  * `:padding`, `:padding_top`, `:padding_right`, `:padding_bottom`, `:padding_left`
  * `:border_color`, `:border_width` — border styling
  * `:corner_radius` — rounded corners
  * `:on_tap` — `{pid, tag}` tuple; fired when card is tapped
  * `:accessibility_id` — test identifier

## Examples

    Dala.Ui.Widgets.card([variant: :elevated, elevation: 2.0, corner_radius: 12], [
      Dala.Ui.Widgets.text(text: "Card content")
    ])

# `carousel`

```elixir
@spec carousel(keyword() | map()) :: map()
```

Returns a `:carousel` leaf node. A horizontally scrolling carousel of items.

## Props

  * `:data` — enumerable of items to render
  * `:id` — atom identifier for the carousel
  * `:on_page_change` — `{pid, tag}` tuple; fired with new page index on swipe
  * `:loop` — boolean, enables infinite looping (default: false)
  * `:peek` — float, peek width for adjacent items

## Examples

    Dala.Ui.Widgets.carousel(id: :photo_carousel, data: assigns.photos, on_page_change: {self(), :page_changed})

# `checkbox`

```elixir
@spec checkbox(keyword() | map()) :: map()
```

Returns a `:checkbox` leaf node. A checkbox with an optional label.

## Props

  * `:value` — boolean, checked state (default: false)
  * `:on_change` — `{pid, tag}` tuple; fired with new boolean value on change
  * `:label` — string, label text displayed beside the checkbox
  * `:color` — color token for the checkbox tint
  * `:enabled` — boolean, whether the checkbox is interactive (default: true)
  * `:accessibility_id` — test identifier

## Examples

    Dala.Ui.Widgets.checkbox(value: true, on_change: {self(), :agree_toggled}, label: "I agree")

# `chip`

```elixir
@spec chip(keyword() | map()) :: map()
```

Returns a `:chip` leaf node. A compact Material Design chip.

## Props

  * `:label` — string, chip text (required)
  * `:variant` — `:assist`, `:filter`, `:input`, or `:suggestion`
  * `:selected` — boolean, selected state (for filter chips)
  * `:on_tap` — `{pid, tag}` tuple; fired when chip is tapped
  * `:icon` — string, icon name displayed before the label
  * `:on_remove` — `{pid, tag}` tuple; fired when remove icon is tapped (input chips)
  * `:enabled` — boolean, whether the chip is interactive
  * `:accessibility_id` — test identifier

## Examples

    Dala.Ui.Widgets.chip(label: "Filter", variant: :filter, selected: true, on_tap: {self(), :chip_tapped})

# `column`

```elixir
@spec column(keyword() | map(), list()) :: map()
```

Returns a `:column` container node. Children are laid out vertically (VStack).

## Props

  * `:gap` — spacing between children (accepts spacing tokens like `:space_md`)
  * `:padding`, `:padding_top`, `:padding_right`, `:padding_bottom`, `:padding_left`
  * `:background` — background color (accepts color tokens)
  * `:border_color`, `:border_width` — optional border
  * `:corner_radius` — rounded corners
  * `:fill_width` — boolean, stretch to fill parent width
  * `:on_tap`, `:on_long_press`, `:on_double_tap`, `:on_swipe*` — gesture handlers
  * `:accessibility_id` — test identifier

## Examples

    Dala.Ui.Widgets.column([padding: :space_md, gap: :space_sm], [
      Dala.Ui.Widgets.text(text: "Title"),
      Dala.Ui.Widgets.text(text: "Subtitle")
    ])

# `date_picker`

```elixir
@spec date_picker(keyword() | map()) :: map()
```

Returns a `:date_picker` leaf node. A date selection dialog.

## Props

  * `:visible` — boolean, whether the picker is shown
  * `:on_select` — `{pid, tag}` tuple; fired with selected date string (ISO 8601)
  * `:on_dismiss` — `{pid, tag}` tuple; fired when the picker is dismissed
  * `:selected_date` — string, initial date in ISO 8601 format
  * `:min_date` — string, earliest selectable date
  * `:max_date` — string, latest selectable date
  * `:title` — string, optional title text

## Examples

    Dala.Ui.Widgets.date_picker(
      visible: true,
      on_select: {self(), :date_picked},
      selected_date: "2025-01-15"
    )

# `divider`

```elixir
@spec divider(keyword() | map()) :: map()
```

Returns a `:divider` leaf node. A horizontal or vertical divider line.

## Props

  * `:thickness` — line thickness in pt (default: 1.0)
  * `:color` — divider color (accepts color tokens, default: `:border`)
  * `:padding` — padding around the divider

## Examples

    Dala.Ui.Widgets.divider()
    Dala.Ui.Widgets.divider(thickness: 2, color: :primary)

# `fab`

```elixir
@spec fab(keyword() | map()) :: map()
```

Returns a `:fab` leaf node. A Floating Action Button.

## Props

  * `:icon` — string, icon name (required)
  * `:on_tap` — `{pid, tag}` tuple; fired when FAB is tapped
  * `:text` — string, optional label for extended FAB
  * `:background` — background color
  * `:color` — icon color
  * `:corner_radius` — rounded corners
  * `:elevation` — float, shadow depth
  * `:accessibility_id` — test identifier

## Examples

    Dala.Ui.Widgets.fab(icon: "add", on_tap: {self(), :add_item})
    Dala.Ui.Widgets.fab(icon: "edit", text: "Compose", on_tap: {self(), :compose})

# `icon`

```elixir
@spec icon(keyword() | map()) :: map()
```

Returns an `:icon` leaf node. Displays a platform-native icon.

Logical icon names are resolved to SF Symbols on iOS and Material Symbols on
Android. Unknown names pass through verbatim (power users can use raw SF Symbol
identifiers like `"globe.americas.fill"`).

## Props

  * `:name` — logical icon name or raw identifier (required)
  * `:text_size` — glyph size in sp
  * `:text_color` — glyph tint color (accepts color tokens)
  * `:padding`, `:background` — layout props
  * `:on_tap`, `:on_long_press` — gesture handlers
  * `:accessibility_id` — test identifier (also used as accessibility label)

## Logical icon names

`settings`, `back`, `forward`, `close`, `add`, `remove`, `edit`, `check`,
`chevron_right`, `chevron_left`, `chevron_up`, `chevron_down`, `info`,
`warning`, `error`, `search`, `trash`, `share`, `more`, `menu`, `refresh`,
`favorite`, `favorite_filled`, `star`, `star_filled`, `user`, `home`

## Examples

    Dala.Ui.Widgets.icon(name: "settings", text_size: 24, text_color: :on_surface)
    Dala.Ui.Widgets.icon(name: "chevron_right", on_tap: {self(), :navigate})

# `icon_button`

```elixir
@spec icon_button(keyword() | map()) :: map()
```

Returns a `:icon_button` leaf node. A clickable icon button.

## Props

  * `:icon` — string, icon name (required)
  * `:on_tap` — `{pid, tag}` tuple; fired when button is tapped
  * `:selected` — boolean, toggle state for toggle icon buttons
  * `:enabled` — boolean, whether the button is interactive
  * `:color` — icon color
  * `:background` — background color
  * `:accessibility_id` — test identifier

## Examples

    Dala.Ui.Widgets.icon_button(icon: "favorite", on_tap: {self(), :favorite_tapped})

# `image`

```elixir
@spec image(keyword() | map()) :: map()
```

Returns an `:image` leaf node. Displays an image from a URL or local asset.

## Props

  * `:src` — URL or local asset name (required)
  * `:resize_mode` — `:cover` (default), `:contain`, `:stretch`, `:repeat`
  * `:width`, `:height` — dimensions in dp/pts; omit to auto-size
  * `:corner_radius` — optional rounded corners
  * `:placeholder_color` — color shown while loading
  * `:accessibility_id` — test identifier

## Examples

    Dala.Ui.Widgets.image(src: "https://example.com/photo.jpg", resize_mode: :cover, corner_radius: 12)

# `list`

```elixir
@spec list(keyword() | map()) :: map()
```

Returns a `:list` node. A data-driven list (FlatList equivalent).

Leverages `Dala.Ui.List` for rendering. Requires an `:id` prop to identify the list
for selection events and custom renderers.

## Props

  * `:data` — enumerable of items to render (mapped to `:items`)
  * `:id` — atom identifier for the list (required for selection events)
  * `:on_end_reached` — `{pid, tag}` tuple; fired when list reaches end
  * `:scroll` — boolean, enables scrolling (default: true)

For custom item rendering, register a renderer via `Dala.Ui.List.put_renderer/3` in `mount/3`.

## Examples

    Dala.Ui.Widgets.list(id: :my_list, data: assigns.items)

    # With custom renderer in mount/3:
    # Dala.Ui.List.put_renderer(socket, :my_list, fn item -> ... end)

# `menu`

```elixir
@spec menu(keyword() | map()) :: map()
```

Returns a `:menu` leaf node. A popup menu with selectable items.

## Props

  * `:items` — list of maps, each with `:label`, `:action` (atom), and optional `:icon`
  * `:visible` — boolean, whether the menu is shown
  * `:on_dismiss` — `{pid, tag}` tuple; fired when the menu is dismissed
  * `:on_select` — `{pid, tag}` tuple; fired with selected item's action atom
  * `:accessibility_id` — test identifier

## Examples

    Dala.Ui.Widgets.menu(
      items: [%{label: "Edit", action: :edit}, %{label: "Delete", action: :delete}],
      visible: true,
      on_select: {self(), :menu_selected}
    )

# `modal`

```elixir
@spec modal(keyword() | map(), list()) :: map()
```

Returns a `:modal` container node. Presents content above the enclosing view.

## Props

  * `:visible` — boolean, controls whether modal is shown (default: false)
  * `:on_dismiss` — `{pid, tag}` tuple; fired when user dismisses modal
  * `:presentation_style` — `:full_screen` (default) or `:page_sheet`

## Examples

    Dala.Ui.Widgets.modal([visible: true, on_dismiss: {self(), :dismissed}], [
      Dala.Ui.Widgets.text(text: "Modal content")
    ])

# `native_view`

```elixir
@spec native_view(module(), keyword() | map()) :: map()
```

Returns a `:native_view` node that renders a platform-native component.

`module` must implement the `Dala.Ui.NativeView` behaviour and be registered
on the native side via `dalaNativeViewRegistry`. The `:id` must be unique
per screen — a duplicate raises at render time.

All other props are passed to `mount/2` and `update/2` on the component.

## Example

    Dala.Ui.Widgets.native_view(MyApp.ChartComponent, id: :revenue_chart, data: @points)

# `nav_bar`

```elixir
@spec nav_bar(keyword() | map()) :: map()
```

Returns a `:nav_bar` leaf node. A bottom navigation bar.

## Props

  * `:items` — list of maps, each with `:id`, `:label`, and `:icon`
  * `:active` — id of the currently active item
  * `:on_select` — `{pid, tag}` tuple; fired with selected item id
  * `:accessibility_id` — test identifier

## Examples

    Dala.Ui.Widgets.nav_bar(
      items: [%{id: "home", label: "Home", icon: "home"}, %{id: "profile", label: "Profile", icon: "user"}],
      active: "home",
      on_select: {self(), :tab_changed}
    )

# `nav_drawer`

```elixir
@spec nav_drawer(keyword() | map()) :: map()
```

Returns a `:nav_drawer` leaf node. A side navigation drawer.

## Props

  * `:visible` — boolean, whether the drawer is shown
  * `:on_dismiss` — `{pid, tag}` tuple; fired when the drawer is dismissed
  * `:items` — list of maps, each with `:id`, `:label`, and `:icon`
  * `:active` — id of the currently active item
  * `:on_select` — `{pid, tag}` tuple; fired with selected item id
  * `:header` — string, optional header text at the top

## Examples

    Dala.Ui.Widgets.nav_drawer(
      visible: true,
      on_dismiss: {self(), :drawer_dismissed},
      items: [%{id: "home", label: "Home", icon: "home"}],
      active: "home",
      on_select: {self(), :nav_changed}
    )

# `nav_rail`

```elixir
@spec nav_rail(keyword() | map()) :: map()
```

Returns a `:nav_rail` leaf node. A side navigation rail (for tablets/desktop).

## Props

  * `:items` — list of maps, each with `:id`, `:label`, and `:icon`
  * `:active` — id of the currently active item
  * `:on_select` — `{pid, tag}` tuple; fired with selected item id
  * `:accessibility_id` — test identifier

## Examples

    Dala.Ui.Widgets.nav_rail(
      items: [%{id: "home", label: "Home", icon: "home"}, %{id: "settings", label: "Settings", icon: "settings"}],
      active: "home",
      on_select: {self(), :rail_changed}
    )

# `pressable`

```elixir
@spec pressable(keyword() | map(), list()) :: map()
```

Returns a `:pressable` container node. A pressable wrapper.

## Props

  * `:on_press` — `{pid, tag}` tuple; fired when pressed
  * `:on_long_press` — `{pid, tag}` tuple; fired on long press

## Examples

    Dala.Ui.Widgets.pressable([on_press: {self(), :card_tapped}], [
      Dala.Ui.Widgets.text(text: "Tap me")
    ])

# `progress_bar`

```elixir
@spec progress_bar(keyword() | map()) :: map()
```

Returns a `:progress_bar` leaf node. Displays a progress bar.

## Props

  * `:progress` — float 0.0 to 1.0, current progress (default: 0.0)
  * `:indeterminate` — boolean, shows indeterminate spinner (default: false)
  * `:color` — progress bar color

# `radio`

```elixir
@spec radio(keyword() | map()) :: map()
```

Returns a `:radio` leaf node. A radio button within a group.

## Props

  * `:selected` — boolean, whether this radio is selected
  * `:on_select` — `{pid, tag}` tuple; fired when this radio is selected
  * `:label` — string, label text displayed beside the radio
  * `:group` — string, radio group name (radios in the same group are mutually exclusive)
  * `:enabled` — boolean, whether the radio is interactive
  * `:color` — color token for the radio tint
  * `:accessibility_id` — test identifier

## Examples

    Dala.Ui.Widgets.radio(selected: true, on_select: {self(), :option_a}, label: "Option A", group: "choices")

# `refresh_control`

```elixir
@spec refresh_control(keyword() | map()) :: map()
```

Returns a `:refresh_control` leaf node. Adds pull-to-refresh to ScrollView.

Attach as a child of `:scroll` node. The scroll node handles the refresh gesture.

## Props

  * `:on_refresh` — `{pid, tag}` tuple; fired when user pulls to refresh
  * `:refreshing` — boolean, true while refresh is in progress
  * `:tint_color` — color of the refresh spinner

# `row`

```elixir
@spec row(keyword() | map(), list()) :: map()
```

Returns a `:row` container node. Children are laid out horizontally (HStack).

Same props as `column/2`.

# `safe_area`

```elixir
@spec safe_area(keyword() | map() | list()) :: map()
```

Returns a `:safe_area` container node. Applies safe area insets.

Renders children within the safe area boundaries (avoiding notches, status bar, etc.).

# `safe_area`

```elixir
@spec safe_area(keyword() | map(), list()) :: map()
```

# `scroll`

```elixir
@spec scroll(keyword() | map(), list()) :: map()
```

Returns a `:scroll` container node. A scrollable view (ScrollView equivalent).

## Props

  * `:direction` — `:vertical` (default) or `:horizontal`
  * `:shows_indicator` — boolean, show scroll indicator (default: true)
  * `:on_end_reached` — `{pid, tag}` tuple; fired when scroll reaches bottom/end
  * `:on_scroll` — `{pid, tag}` tuple; fired during scrolling with scroll position
  * `:padding`, `:background` — layout props

## Examples

    Dala.Ui.Widgets.scroll([padding: :space_md], [
      Dala.Ui.Widgets.text(text: "Long content...")
    ])

# `search_bar`

```elixir
@spec search_bar(keyword() | map()) :: map()
```

Returns a `:search_bar` leaf node. A search input bar with placeholder and callbacks.

## Props

  * `:placeholder` — string, placeholder text when empty
  * `:text` — string, current search text
  * `:on_change` — `{pid, tag}` tuple; fired on every text change
  * `:on_submit` — `{pid, tag}` tuple; fired when search is submitted
  * `:on_focus` — `{pid, tag}` tuple; fired when the bar gains focus
  * `:active` — boolean, whether the search bar is in active/expanded state
  * `:on_tap` — `{pid, tag}` tuple; fired when the search bar is tapped
  * `:accessibility_id` — test identifier

## Examples

    Dala.Ui.Widgets.search_bar(placeholder: "Search...", on_change: {self(), :search_changed}, on_submit: {self(), :search_submitted})

# `segmented_button`

```elixir
@spec segmented_button(keyword() | map()) :: map()
```

Returns a `:segmented_button` leaf node. A segmented control with multiple segments.

## Props

  * `:segments` — list of maps, each with `:id`, `:label`, and optional `:icon`
  * `:selected` — the id of the currently selected segment
  * `:on_select` — `{pid, tag}` tuple; fired with selected segment id
  * `:accessibility_id` — test identifier

## Examples

    Dala.Ui.Widgets.segmented_button(
      segments: [%{id: "day", label: "Day"}, %{id: "week", label: "Week"}, %{id: "month", label: "Month"}],
      selected: "week",
      on_select: {self(), :range_changed}
    )

# `slider`

```elixir
@spec slider(keyword() | map()) :: map()
```

Returns a `:slider` leaf node. A continuous range slider.

## Props

  * `:value` — current value (default: 0.5)
  * `:min_value` — minimum value (default: 0.0)
  * `:max_value` — maximum value (default: 1.0)
  * `:on_change` — `{pid, tag}` tuple; fired with new float value on drag
  * `:color` — slider tint color
  * `:accessibility_id` — test identifier

## Examples

    Dala.Ui.Widgets.slider(value: 0.5, min_value: 0, max_value: 100, on_change: {self(), :volume_changed})

# `snackbar`

```elixir
@spec snackbar(keyword() | map()) :: map()
```

Returns a `:snackbar` leaf node. A transient message bar with an optional action.

## Props

  * `:message` — string, the message text (required)
  * `:action_label` — string, label for the optional action button
  * `:on_action` — `{pid, tag}` tuple; fired when the action button is tapped
  * `:duration` — `:short` or `:long`
  * `:visible` — boolean, whether the snackbar is shown

## Examples

    Dala.Ui.Widgets.snackbar(message: "Item deleted", action_label: "Undo", on_action: {self(), :undo})

# `spacer`

```elixir
@spec spacer(keyword() | map()) :: map()
```

Returns a `:spacer` leaf node. Flexible or fixed space.

## Props

  * `:size` — fixed size in pt (omit for flexible spacer that fills available space)

## Examples

    Dala.Ui.Widgets.spacer()          # flexible — fills available space
    Dala.Ui.Widgets.spacer(size: 20)  # fixed 20pt gap

# `status_bar`

```elixir
@spec status_bar(keyword() | map()) :: map()
```

Returns a `:status_bar` leaf node. Controls the status bar appearance.

## Props

  * `:bar_style` — `:default` (dark text) or `:light_content` (light text)
  * `:hidden` — boolean, hides the status bar (default: false)

# `switch`

```elixir
@spec switch(keyword() | map()) :: map()
```

Returns a `:switch` leaf node. A boolean toggle switch.

Prefer `toggle/1` for new code — it uses `:on_change` consistent with other
value widgets. This function is kept for backward compatibility.

## Props

  * `:value` — boolean, on/off state (default: false)
  * `:on_toggle` — `{pid, tag}` tuple; fires `{:toggle, tag, new_value}` to handler
  * `:track_color` — color when switch is on
  * `:thumb_color` — color of the draggable thumb

# `tab_bar`

```elixir
@spec tab_bar(keyword() | map()) :: map()
```

Returns a `:tab_bar` container node. A tab navigation bar.

## Props

  * `:tabs` — list of tab definitions, each a map with `:id`, `:label`, and optional `:icon`
  * `:active_tab` — the id of the currently selected tab
  * `:on_tab_select` — `{pid, tag}` tuple; fired with selected tab id string
  * `:accessibility_id` — test identifier

## Examples

    Dala.Ui.Widgets.tab_bar(
      tabs: [
        %{id: "home", label: "Home", icon: "home"},
        %{id: "settings", label: "Settings", icon: "settings"}
      ],
      active_tab: "home",
      on_tab_select: {self(), :tab_changed}
    )

# `text`

```elixir
@spec text(keyword() | map()) :: map()
```

Returns a `:text` leaf node.

## Props

  * `:text` — the string to display (required)
  * `:text_color` — color value (accepts color tokens like `:on_surface`)
  * `:text_size` — font size (accepts size tokens like `:xl` or numeric sp)
  * `:font_weight` — `"regular"`, `"medium"`, `"semibold"`, `"bold"`, `"light"`, `"thin"`
  * `:font_family` — custom font family name (nil = system font)
  * `:text_align` — `:left`, `:center`, `:right`
  * `:italic` — boolean
  * `:line_height` — multiplier (e.g. `1.5` for 150% line height)
  * `:letter_spacing` — extra spacing in pt
  * `:padding`, `:padding_top`, `:padding_right`, `:padding_bottom`, `:padding_left`
  * `:background` — background color
  * `:corner_radius` — rounded corners
  * `:fill_width` — boolean, stretch to fill parent width
  * `:on_tap`, `:on_long_press`, `:on_double_tap` — gesture handlers
  * `:accessibility_id` — test identifier

## Examples

    Dala.Ui.Widgets.text(text: "Hello")
    Dala.Ui.Widgets.text(text: "Title", text_size: :xl, font_weight: "bold", text_color: :on_surface)

# `text_field`

```elixir
@spec text_field(keyword() | map()) :: map()
```

Returns a `:text_field` leaf node. A single-line text input.

## Props

  * `:text` — initial/current text value
  * `:placeholder` — placeholder text when empty
  * `:on_change` — `{pid, tag}` tuple; fired on every text change with new value
  * `:on_focus` — `{pid, tag}` tuple; fired when field gains focus
  * `:on_blur` — `{pid, tag}` tuple; fired when field loses focus
  * `:on_submit` — `{pid, tag}` tuple; fired when return key is pressed
  * `:on_compose` — `{pid, tag}` tuple; IME composition events (CJK, etc.)
  * `:keyboard_type` — `:default`, `:number`, `:decimal`, `:email`, `:phone`, `:url`
  * `:return_key` — `:done`, `:next`, `:go`, `:search`, `:send`
  * `:text_color`, `:text_size` — typography
  * `:background`, `:padding`, `:corner_radius` — layout
  * `:accessibility_id` — test identifier

## Examples

    Dala.Ui.Widgets.text_field(placeholder: "Enter name", on_change: {self(), :name_changed})
    Dala.Ui.Widgets.text_field(keyboard_type: :email, return_key: :next, on_submit: {self(), :next_field})

# `time_picker`

```elixir
@spec time_picker(keyword() | map()) :: map()
```

Returns a `:time_picker` leaf node. A time selection dialog.

## Props

  * `:visible` — boolean, whether the picker is shown
  * `:on_select` — `{pid, tag}` tuple; fired with selected time string (HH:MM)
  * `:on_dismiss` — `{pid, tag}` tuple; fired when the picker is dismissed
  * `:selected_time` — string, initial time in HH:MM format
  * `:title` — string, optional title text

## Examples

    Dala.Ui.Widgets.time_picker(
      visible: true,
      on_select: {self(), :time_picked},
      selected_time: "09:30"
    )

# `toggle`

```elixir
@spec toggle(keyword() | map()) :: map()
```

Returns a `:toggle` leaf node. A boolean toggle switch.

## Props

  * `:value` — boolean, on/off state (default: false)
  * `:on_change` — `{pid, tag}` tuple; fired with new boolean value on toggle
  * `:text` — optional label text displayed beside the switch
  * `:track_color` — color when switch is on
  * `:thumb_color` — color of the draggable thumb
  * `:accessibility_id` — test identifier

## Examples

    Dala.Ui.Widgets.toggle(value: true, on_change: {self(), :notifications_toggled}, text: "Notifications")

# `tooltip`

```elixir
@spec tooltip(keyword() | map(), list()) :: map()
```

Returns a `:tooltip` container node. Shows a tooltip over its children.

## Props

  * `:text` — string, tooltip text (required)
  * `:position` — `:top`, `:bottom`, `:left`, or `:right`

## Examples

    Dala.Ui.Widgets.tooltip([text: "Save changes", position: :top], [
      Dala.Ui.Widgets.icon(name: "save")
    ])

# `video`

```elixir
@spec video(keyword() | map()) :: map()
```

Returns a `:video` leaf node. An inline video player.

## Props

  * `:src` — video URL (required)
  * `:autoplay` — boolean, start playing immediately (default: false)
  * `:loop` — boolean, loop playback (default: false)
  * `:controls` — boolean, show playback controls (default: true)
  * `:width`, `:height` — dimensions in dp/pts; omit to fill parent

## Examples

    Dala.Ui.Widgets.video(src: "https://example.com/clip.mp4", autoplay: true, loop: true)

# `webview`

```elixir
@spec webview(keyword() | map()) :: map()
```

Returns a `:webview` component node. Renders a native web view inline.

The JS bridge is injected automatically — the page can call `window.dala.send(data)`
to deliver messages to `handle_info({:webview, :message, data}, socket)`, and
Elixir can push to JS via `Dala.WebView.post_message/2`.

## Props

  * `:url` — URL to load (required)
  * `:allow` — list of URL prefixes that navigation is permitted to (default: allow all).
    Blocked attempts arrive as `{:webview, :blocked, url}` in `handle_info`.
  * `:show_url` — show a native URL label above the WebView (default: false)
  * `:title` — static title label above the WebView; overrides `:show_url`
  * `:width`, `:height` — dimensions in dp/pts; omit to fill parent

---

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