Plushie.Widget.PickList (Plushie v0.7.0)

Pick list, dropdown selection.

Props

Name	Type	Default	Description
`options`	`[String.t() \| atom()]`	required	Available choices.
`selected`	`String.t() \| atom()`	`nil`	Currently selected value.
`placeholder`	`String.t() \| atom()`	`nil`	Placeholder text when nothing is selected.
`width`	`:fill \| :shrink \| {:fill_portion, pos_integer()} \| number()`	`nil`	Widget width. Default: shrink.
`padding`	`number() \| {number(), number()} \| %Plushie.Type.Padding{}`	`nil`	Internal padding.
`text_size`	`number()`	`nil`	Text size in pixels.
`font`	`:default \| :monospace \| String.t() \| %Plushie.Type.Font{}`	`nil`	Font specification.
`line_height`	`number() \| %{relative: number()} \| %{absolute: number()}`	`nil`	Text line height.
`menu_height`	`number()`	`nil`	Maximum dropdown menu height in pixels.
`shaping`	`:basic \| :advanced \| :auto`	`nil`	Text shaping strategy.
`handle`	`map()`	`nil`	Dropdown handle indicator customization.
`ellipsis`	`:none \| :start \| :middle \| :end`	`nil`	Text ellipsis: `:none`, `:start`, `:middle`, or `:end`.
`menu_style`	`map()`	`nil`	Inline style for the dropdown menu.

| style | :default \| :primary \| :secondary \| :success \| :danger \| :warning \| :dark \| :weak \| :rounded_box \| term() | nil | Named preset or custom StyleMap. | | on_open | boolean() | nil | Emit open event when the dropdown opens. | | on_close | boolean() | nil | Emit close event when the dropdown closes. | | required | boolean() | nil | Marks the field as required. Flows into a11y.required automatically. | | validation | term() | nil | Form validation state. Accepts :valid, :pending, or {:invalid, message}. Flows into a11y.invalid and a11y.error_message automatically. | | event_rate | integer() | nil | Max events per second for coalescable events. | | a11y | %Plushie.Type.A11y{} \| map() \| keyword() | %{role: :combo_box, label_from: :placeholder, has_popup: "listbox"} | Accessibility annotations. |

Events

Event	Type	Description
`:select`	`value: String.t() \| atom()`	Emitted when an option is selected.
`:open`	none	Emitted when dropdown opens (requires `on_open: true`).
`:close`	none	Emitted when dropdown closes (requires `on_close: true`).

Constructor

PickList.new(id, options)
PickList.new(id, options, opts)

Summary

Types

option()

t()

Functions

a11y(widget, descriptor)

Accessibility annotations.

build(widget)

Converts this widget struct to a ui_node() map.

ellipsis(widget, descriptor)

Text ellipsis: :none, :start, :middle, or :end.

event_rate(widget, descriptor)

Max events per second for coalescable events.

font(widget, descriptor)

Font specification.

handle(widget, descriptor)

Dropdown handle indicator customization.

line_height(widget, descriptor)

Text line height.

menu_height(widget, descriptor)

Maximum dropdown menu height in pixels.

menu_style(widget, descriptor)

Inline style for the dropdown menu.

new(id, options, opts \\ [])

Creates a new widget struct with the given positional args and keyword options.

on_close(widget, descriptor)

Emit close event when the dropdown closes.

on_open(widget, descriptor)

Emit open event when the dropdown opens.

options(widget, descriptor)

Available choices.

padding(widget, descriptor)

Internal padding.

pick_list(id, opts \\ [])

Creates a :pick_list widget.

placeholder(widget, descriptor)

Placeholder text when nothing is selected.

required(widget, descriptor)

Marks the field as required. Flows into a11y.required automatically.

selected(widget, descriptor)

Currently selected value.

shaping(widget, descriptor)

Text shaping strategy.

style(widget, descriptor)

Named preset or custom StyleMap.

text_size(widget, descriptor)

Text size in pixels.

validation(widget, descriptor)

Form validation state. Accepts :valid, :pending, or {:invalid, message}. Flows into a11y.invalid and a11y.error_message automatically.

width(widget, descriptor)

Widget width. Default: shrink.

with_options(widget, opts)

Applies keyword options to an existing widget struct.

Types

option()

@type option() ::
  ((((((((((((((((({:selected, String.t() | atom()}
                   | {:placeholder, String.t() | atom()})
                  | {:width,
                     :fill | :shrink | {:fill_portion, pos_integer()} | number()})
                 | {:padding,
                    number()
                    | {number(), number()}
                    | %Plushie.Type.Padding{
                        bottom: term(),
                        left: term(),
                        right: term(),
                        top: term()
                      }})
                | {:text_size, number()})
               | {:font,
                  :default
                  | :monospace
                  | String.t()
                  | %Plushie.Type.Font{
                      family: term(),
                      stretch: term(),
                      style: term(),
                      weight: term()
                    }})
              | {:line_height,
                 number() | %{relative: number()} | %{absolute: number()}})
             | {:menu_height, number()})
            | {:shaping, :basic | :advanced | :auto})
           | {:handle, map()})
          | {:ellipsis, :none | :start | :middle | :end})
         | {:menu_style, map()})
        | {:style,
           :default
           | :primary
           | :secondary
           | :success
           | :danger
           | :warning
           | :dark
           | :weak
           | :rounded_box
           | term()})
       | {:on_open, boolean()})
      | {:on_close, boolean()})
     | {:required, boolean()})
    | {:validation, term()})
   | {:event_rate, integer()})
  | {:a11y,
     %Plushie.Type.A11y{
       active_descendant: term(),
       busy: term(),
       described_by: term(),
       description: term(),
       disabled: term(),
       error_message: term(),
       expanded: term(),
       has_popup: term(),
       hidden: term(),
       invalid: term(),
       label: term(),
       label_from: term(),
       labelled_by: term(),
       level: term(),
       live: term(),
       mnemonic: term(),
       modal: term(),
       orientation: term(),
       position_in_set: term(),
       radio_group: term(),
       read_only: term(),
       required: term(),
       role: term(),
       selected: term(),
       size_of_set: term(),
       toggled: term(),
       value: term()
     }
     | map()
     | keyword()}

t()

@type t() :: %Plushie.Widget.PickList{
  a11y:
    (%Plushie.Type.A11y{
       active_descendant: term(),
       busy: term(),
       described_by: term(),
       description: term(),
       disabled: term(),
       error_message: term(),
       expanded: term(),
       has_popup: term(),
       hidden: term(),
       invalid: term(),
       label: term(),
       label_from: term(),
       labelled_by: term(),
       level: term(),
       live: term(),
       mnemonic: term(),
       modal: term(),
       orientation: term(),
       position_in_set: term(),
       radio_group: term(),
       read_only: term(),
       required: term(),
       role: term(),
       selected: term(),
       size_of_set: term(),
       toggled: term(),
       value: term()
     }
     | map()
     | keyword())
    | Plushie.Animation.Transition.t()
    | Plushie.Animation.Spring.t()
    | Plushie.Animation.Sequence.t()
    | nil,
  ellipsis:
    (:none | :start | :middle | :end)
    | Plushie.Animation.Transition.t()
    | Plushie.Animation.Spring.t()
    | Plushie.Animation.Sequence.t()
    | nil,
  event_rate:
    integer()
    | Plushie.Animation.Transition.t()
    | Plushie.Animation.Spring.t()
    | Plushie.Animation.Sequence.t()
    | nil,
  font:
    (:default
     | :monospace
     | String.t()
     | %Plushie.Type.Font{
         family: term(),
         stretch: term(),
         style: term(),
         weight: term()
       })
    | Plushie.Animation.Transition.t()
    | Plushie.Animation.Spring.t()
    | Plushie.Animation.Sequence.t()
    | nil,
  handle:
    map()
    | Plushie.Animation.Transition.t()
    | Plushie.Animation.Spring.t()
    | Plushie.Animation.Sequence.t()
    | nil,
  id: String.t(),
  line_height:
    (number() | %{relative: number()} | %{absolute: number()})
    | Plushie.Animation.Transition.t()
    | Plushie.Animation.Spring.t()
    | Plushie.Animation.Sequence.t()
    | nil,
  menu_height:
    number()
    | Plushie.Animation.Transition.t()
    | Plushie.Animation.Spring.t()
    | Plushie.Animation.Sequence.t()
    | nil,
  menu_style:
    map()
    | Plushie.Animation.Transition.t()
    | Plushie.Animation.Spring.t()
    | Plushie.Animation.Sequence.t()
    | nil,
  on_close:
    boolean()
    | Plushie.Animation.Transition.t()
    | Plushie.Animation.Spring.t()
    | Plushie.Animation.Sequence.t()
    | nil,
  on_open:
    boolean()
    | Plushie.Animation.Transition.t()
    | Plushie.Animation.Spring.t()
    | Plushie.Animation.Sequence.t()
    | nil,
  options:
    [String.t() | atom()]
    | Plushie.Animation.Transition.t()
    | Plushie.Animation.Spring.t()
    | Plushie.Animation.Sequence.t()
    | nil,
  padding:
    (number()
     | {number(), number()}
     | %Plushie.Type.Padding{
         bottom: term(),
         left: term(),
         right: term(),
         top: term()
       })
    | Plushie.Animation.Transition.t()
    | Plushie.Animation.Spring.t()
    | Plushie.Animation.Sequence.t()
    | nil,
  placeholder:
    (String.t() | atom())
    | Plushie.Animation.Transition.t()
    | Plushie.Animation.Spring.t()
    | Plushie.Animation.Sequence.t()
    | nil,
  required:
    boolean()
    | Plushie.Animation.Transition.t()
    | Plushie.Animation.Spring.t()
    | Plushie.Animation.Sequence.t()
    | nil,
  selected:
    (String.t() | atom())
    | Plushie.Animation.Transition.t()
    | Plushie.Animation.Spring.t()
    | Plushie.Animation.Sequence.t()
    | nil,
  shaping:
    (:basic | :advanced | :auto)
    | Plushie.Animation.Transition.t()
    | Plushie.Animation.Spring.t()
    | Plushie.Animation.Sequence.t()
    | nil,
  style:
    (:default
     | :primary
     | :secondary
     | :success
     | :danger
     | :warning
     | :dark
     | :weak
     | :rounded_box
     | term())
    | Plushie.Animation.Transition.t()
    | Plushie.Animation.Spring.t()
    | Plushie.Animation.Sequence.t()
    | nil,
  text_size:
    number()
    | Plushie.Animation.Transition.t()
    | Plushie.Animation.Spring.t()
    | Plushie.Animation.Sequence.t()
    | nil,
  validation:
    term()
    | Plushie.Animation.Transition.t()
    | Plushie.Animation.Spring.t()
    | Plushie.Animation.Sequence.t()
    | nil,
  width:
    (:fill | :shrink | {:fill_portion, pos_integer()} | number())
    | Plushie.Animation.Transition.t()
    | Plushie.Animation.Spring.t()
    | Plushie.Animation.Sequence.t()
    | nil
}

Functions

build(widget)

@spec build(widget :: t()) :: Plushie.Widget.ui_node()

Converts this widget struct to a ui_node() map.

ellipsis(widget, descriptor)

@spec ellipsis(widget :: t(), value :: (:none | :start | :middle | :end) | nil) :: t()

Text ellipsis: :none, :start, :middle, or :end.

Accepts :none | :start | :middle | :end.

event_rate(widget, descriptor)

@spec event_rate(widget :: t(), value :: integer() | nil) :: t()

Max events per second for coalescable events.

Accepts integer().

font(widget, descriptor)

@spec font(
  widget :: t(),
  value ::
    (:default
     | :monospace
     | String.t()
     | %Plushie.Type.Font{
         family: term(),
         stretch: term(),
         style: term(),
         weight: term()
       })
    | nil
) :: t()

Font specification.

Accepts :default | :monospace | String.t() | %Plushie.Type.Font{}.

handle(widget, descriptor)

@spec handle(widget :: t(), value :: map() | nil) :: t()

Dropdown handle indicator customization.

Accepts map().

line_height(widget, descriptor)

@spec line_height(
  widget :: t(),
  value :: (number() | %{relative: number()} | %{absolute: number()}) | nil
) :: t()

Text line height.

Accepts number() | %{relative: number()} | %{absolute: number()}.

menu_height(widget, descriptor)

@spec menu_height(widget :: t(), value :: number() | nil) :: t()

Maximum dropdown menu height in pixels.

Accepts number().

menu_style(widget, descriptor)

@spec menu_style(widget :: t(), value :: map() | nil) :: t()

Inline style for the dropdown menu.

Accepts map().

new(id, options, opts \\ [])

Creates a new widget struct with the given positional args and keyword options.

Arguments

id - unique widget identifier
options - Available choices.
opts - keyword list of optional props

on_close(widget, descriptor)

@spec on_close(widget :: t(), value :: boolean() | nil) :: t()

Emit close event when the dropdown closes.

Accepts boolean().

on_open(widget, descriptor)

@spec on_open(widget :: t(), value :: boolean() | nil) :: t()

Emit open event when the dropdown opens.

Accepts boolean().

options(widget, descriptor)

@spec options(widget :: t(), value :: [String.t() | atom()]) :: t()

Available choices.

Accepts [String.t() | atom()].

padding(widget, descriptor)

@spec padding(
  widget :: t(),
  value ::
    (number()
     | {number(), number()}
     | %Plushie.Type.Padding{
         bottom: term(),
         left: term(),
         right: term(),
         top: term()
       })
    | nil
) :: t()

Internal padding.

Accepts number() | {number(), number()} | %Plushie.Type.Padding{}.

pick_list(id, opts \\ [])

(macro)

Creates a :pick_list widget.

Shorthand for new/2. Import this macro to use the widget name directly in view functions:

import Plushie.Widget.PickList, only: [pick_list: 2]

pick_list("my-id", prop: value)

placeholder(widget, descriptor)

@spec placeholder(widget :: t(), value :: (String.t() | atom()) | nil) :: t()

Placeholder text when nothing is selected.

Accepts String.t() | atom().

required(widget, descriptor)

@spec required(widget :: t(), value :: boolean() | nil) :: t()

Marks the field as required. Flows into a11y.required automatically.

Accepts boolean().

selected(widget, descriptor)

@spec selected(widget :: t(), value :: (String.t() | atom()) | nil) :: t()

Currently selected value.

Accepts String.t() | atom().

shaping(widget, descriptor)

@spec shaping(widget :: t(), value :: (:basic | :advanced | :auto) | nil) :: t()

Text shaping strategy.

Accepts :basic | :advanced | :auto.

style(widget, descriptor)

@spec style(
  widget :: t(),
  value ::
    (:default
     | :primary
     | :secondary
     | :success
     | :danger
     | :warning
     | :dark
     | :weak
     | :rounded_box
     | term())
    | nil
) :: t()

Named preset or custom StyleMap.

text_size(widget, descriptor)

@spec text_size(widget :: t(), value :: number() | nil) :: t()

Text size in pixels.

Accepts number().

validation(widget, descriptor)

@spec validation(widget :: t(), value :: term() | nil) :: t()

Form validation state. Accepts :valid, :pending, or {:invalid, message}. Flows into a11y.invalid and a11y.error_message automatically.

Accepts term().

width(widget, descriptor)

@spec width(
  widget :: t(),
  value :: (:fill | :shrink | {:fill_portion, pos_integer()} | number()) | nil
) ::
  t()

Widget width. Default: shrink.

Accepts :fill | :shrink | {:fill_portion, pos_integer()} | number().

with_options(widget, opts)

@spec with_options(widget :: t(), opts :: [option()]) :: t()

Applies keyword options to an existing widget struct.