# `PhiaUi.Components.SpecialInputs`
[🔗](https://github.com/charlenopires/PhiaUI/blob/v0.1.17/lib/phia_ui/components/inputs/special_inputs.ex#L1)

Specialized form input components: currency, masked input, two-thumb range slider,
signature pad, floating labels, swatch picker, form stepper, and country selector.

## Components

| Function | Purpose | JS Hook |
|---|---|---|
| `currency_input/1` | Number input with currency symbol | none |
| `form_currency_input/1` | Ecto-integrated currency input | none |
| `masked_input/1` | Pattern-masked text input | PhiaMaskedInput |
| `form_masked_input/1` | Ecto-integrated masked input | PhiaMaskedInput |
| `range_slider/1` | Two-thumb range slider | PhiaRangeSlider |
| `form_range_slider/1` | Ecto-integrated two-thumb slider | PhiaRangeSlider |
| `signature_pad/1` | Canvas freehand signature | PhiaSignaturePad |
| `color_swatch_picker/1` | Preset color swatch grid | none |
| `form_color_swatch_picker/1` | Ecto-integrated swatch picker | none |
| `float_input/1` | Text input with floating label | none |
| `form_float_input/1` | Ecto-integrated floating label input | none |
| `float_textarea/1` | Textarea with floating label | none |
| `form_float_textarea/1` | Ecto-integrated floating label textarea | none |
| `form_feedback/1` | Form-level status alert | none |
| `input_status/1` | Per-field validation status icon | none |
| `form_stepper/1` | Multi-step form progress indicator | none |
| `form_stepper_item/1` | Individual step item | none |
| `country_select/1` | Country selector with ISO 3166-1 options | none |
| `form_country_select/1` | Ecto-integrated country selector | none |

# `color_swatch_picker`

Renders a grid of preset color swatch buttons. No JavaScript required.

The selected swatch gets a visible border ring. Clicking sends a `phx-click` or
`phx-change` event depending on how you wire it.

## Example

    <.color_swatch_picker
      name="brand_color"
      value={@brand_color}
      swatches={["#ef4444", "#f97316", "#eab308", "#22c55e", "#3b82f6", "#8b5cf6"]}
    />

## Attributes

* `name` (`:string`) - Defaults to `nil`.
* `swatches` (`:list`) (required) - List of hex color strings, e.g. ["#ff0000", ...].
* `value` (`:string`) - Currently selected hex color. Defaults to `nil`.
* `size` (`:string`) - Swatch button size: sm | md | lg. Defaults to `"md"`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted. Supports all globals plus: `["phx-change"]`.

# `country_select`

Renders a styled `<select>` populated with ISO 3166-1 alpha-2 countries.

## Example

    <.country_select name="country" value={@country} />
    <.country_select name="phone_country" value="US" include_dial_code={true} />

## Attributes

* `id` (`:string`) - Defaults to `nil`.
* `name` (`:string`) - Defaults to `nil`.
* `value` (`:string`) - ISO 3166-1 alpha-2 country code, e.g. "US". Defaults to `nil`.
* `include_dial_code` (`:boolean`) - Append dial code to option labels. Defaults to `false`.
* `prompt` (`:string`) - Defaults to `"Select a country..."`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted. Supports all globals plus: `["phx-change", "disabled", "required"]`.

# `currency_input`

Renders a number input with a currency symbol prefix or suffix. No JavaScript required.

## Example

    <.currency_input name="price" value={@price} symbol="$" symbol_position="left" />
    <.currency_input name="amount" value={@amount} symbol="€" symbol_position="right" />

## Attributes

* `id` (`:string`) - Defaults to `nil`.
* `name` (`:string`) - Defaults to `nil`.
* `value` (`:any`) - Defaults to `nil`.
* `symbol` (`:string`) - Currency symbol to display. Defaults to `"$"`.
* `symbol_position` (`:string`) - left | right. Defaults to `"left"`.
* `placeholder` (`:string`) - Defaults to `"0.00"`.
* `disabled` (`:boolean`) - Defaults to `false`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted. Supports all globals plus: `["phx-change", "phx-blur", "phx-debounce", "step", "min", "max"]`.

# `float_input`

Renders a text input with a CSS-only floating label (MUI / Mantine style).

The label starts positioned over the input (placeholder position). It floats up
when the input gains focus or has a value, via Tailwind `peer` classes.

Requires `placeholder=" "` (single space) on the input — this is how the
`peer-placeholder-shown:*` CSS trick detects whether the input is empty.

## Example

    <.float_input id="email" name="email" label="Email address" type="email" />

## Attributes

* `id` (`:string`) - Defaults to `nil`.
* `name` (`:string`) - Defaults to `nil`.
* `label` (`:string`) (required) - Floating label text.
* `type` (`:string`) - Defaults to `"text"`.
* `value` (`:string`) - Defaults to `""`.
* `disabled` (`:boolean`) - Defaults to `false`.
* `error` (`:boolean`) - Apply destructive styling. Defaults to `false`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted. Supports all globals plus: `["phx-change", "phx-blur", "phx-debounce", "autocomplete", "readonly", "required"]`.

# `float_textarea`

Renders a textarea with a CSS-only floating label. Same pattern as `float_input/1`.

## Attributes

* `id` (`:string`) - Defaults to `nil`.
* `name` (`:string`) - Defaults to `nil`.
* `label` (`:string`) (required) - Floating label text.
* `rows` (`:integer`) - Defaults to `4`.
* `value` (`:string`) - Defaults to `""`.
* `disabled` (`:boolean`) - Defaults to `false`.
* `error` (`:boolean`) - Defaults to `false`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted. Supports all globals plus: `["phx-change", "phx-blur", "phx-debounce", "readonly", "required"]`.

# `form_color_swatch_picker`

Renders a color swatch picker integrated with `Phoenix.HTML.FormField`.
## Attributes

* `field` (`Phoenix.HTML.FormField`) (required)
* `label` (`:string`) - Defaults to `nil`.
* `swatches` (`:list`) (required)
* `size` (`:string`) - Defaults to `"md"`.
* `class` (`:string`) - Defaults to `nil`.

# `form_country_select`

Renders a country select integrated with `Phoenix.HTML.FormField`.
## Attributes

* `field` (`Phoenix.HTML.FormField`) (required)
* `label` (`:string`) - Defaults to `nil`.
* `description` (`:string`) - Defaults to `nil`.
* `include_dial_code` (`:boolean`) - Defaults to `false`.
* `class` (`:string`) - Defaults to `nil`.

# `form_currency_input`

Renders a currency input integrated with `Phoenix.HTML.FormField`.
## Attributes

* `field` (`Phoenix.HTML.FormField`) (required)
* `label` (`:string`) - Defaults to `nil`.
* `description` (`:string`) - Defaults to `nil`.
* `symbol` (`:string`) - Defaults to `"$"`.
* `symbol_position` (`:string`) - Defaults to `"left"`.
* `class` (`:string`) - Defaults to `nil`.

# `form_feedback`

Renders a form-level status alert for submission outcomes or validation summaries.

## Example

    <.form_feedback status="success" title="Saved!" message="Your changes have been saved." />
    <.form_feedback status="error" title="Failed" message="Unable to save. Please try again." />

## Attributes

* `status` (`:string`) (required) - success | error | warning | info.
* `title` (`:string`) - Defaults to `nil`.
* `message` (`:string`) - Defaults to `nil`.
* `class` (`:string`) - Defaults to `nil`.
## Slots

* `inner_block`

# `form_float_input`

Renders a floating-label input integrated with `Phoenix.HTML.FormField`.
## Attributes

* `field` (`Phoenix.HTML.FormField`) (required)
* `label` (`:string`) (required)
* `type` (`:string`) - Defaults to `"text"`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted. Supports all globals plus: `["phx-debounce", "autocomplete", "readonly", "disabled"]`.

# `form_float_textarea`

Renders a floating-label textarea integrated with `Phoenix.HTML.FormField`.
## Attributes

* `field` (`Phoenix.HTML.FormField`) (required)
* `label` (`:string`) (required)
* `rows` (`:integer`) - Defaults to `4`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted. Supports all globals plus: `["phx-debounce", "readonly", "disabled"]`.

# `form_masked_input`

Renders a masked input integrated with `Phoenix.HTML.FormField`.
## Attributes

* `field` (`Phoenix.HTML.FormField`) (required)
* `label` (`:string`) - Defaults to `nil`.
* `description` (`:string`) - Defaults to `nil`.
* `mask` (`:string`) (required)
* `class` (`:string`) - Defaults to `nil`.

# `form_range_slider`

Renders a two-thumb range slider integrated with two `Phoenix.HTML.FormField` structs.
## Attributes

* `field_from` (`Phoenix.HTML.FormField`) (required)
* `field_to` (`Phoenix.HTML.FormField`) (required)
* `label` (`:string`) - Defaults to `nil`.
* `min` (`:integer`) - Defaults to `0`.
* `max` (`:integer`) - Defaults to `100`.
* `step` (`:integer`) - Defaults to `1`.
* `class` (`:string`) - Defaults to `nil`.

# `form_stepper`

Renders a multi-step form progress indicator.

Steps are auto-classified as `"complete"`, `"active"`, or `"pending"` based on
`:current_step`, unless an explicit `:status` key is provided in the step map.

## Example

    <.form_stepper
      current_step={2}
      steps={[
        %{label: "Account"},
        %{label: "Profile"},
        %{label: "Billing"},
        %{label: "Confirm"}
      ]}
    />

## Attributes

* `steps` (`:list`) (required) - List of step maps with :label, optional :description, optional :status.
* `current_step` (`:integer`) - 1-based active step index. Defaults to `1`.
* `orientation` (`:string`) - horizontal | vertical. Defaults to `"horizontal"`.
* `class` (`:string`) - Defaults to `nil`.

# `form_stepper_item`

Renders a single standalone step item for manual stepper layouts.
## Attributes

* `step` (`:integer`) (required) - 1-based step number shown inside the indicator.
* `label` (`:string`) (required)
* `description` (`:string`) - Defaults to `nil`.
* `status` (`:string`) - pending | active | complete | error. Defaults to `"pending"`.
* `class` (`:string`) - Defaults to `nil`.

# `input_status`

Renders a per-field validation status icon.

- `valid` → green checkmark
- `invalid` → red X
- `pending` → spinning loader
- `none` → renders nothing

## Attributes

* `status` (`:string`) (required) - valid | invalid | pending | none.
* `class` (`:string`) - Defaults to `nil`.

# `masked_input`

Renders a pattern-masked text input powered by the `PhiaMaskedInput` JS hook.

The hook intercepts `input` events and enforces the mask by stripping invalid
characters and inserting mask literals at the correct positions.

Mask syntax: `#` = digit, `A` = letter, `*` = any character.

## Examples

    <%!-- US phone number --%>
    <.masked_input id="phone" name="phone" mask="(###) ###-####" />

    <%!-- Date --%>
    <.masked_input id="dob" name="dob" mask="##/##/####" />

    <%!-- Credit card --%>
    <.masked_input id="cc" name="cc" mask="#### #### #### ####" />

## Attributes

* `id` (`:string`) (required) - Required for phx-hook.
* `name` (`:string`) - Defaults to `nil`.
* `value` (`:string`) - Defaults to `""`.
* `mask` (`:string`) (required) - Mask pattern: # = digit, A = letter, * = any.
* `placeholder` (`:string`) - Defaults to `nil`.
* `disabled` (`:boolean`) - Defaults to `false`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted. Supports all globals plus: `["phx-change", "phx-blur", "phx-debounce"]`.

# `range_slider`

Renders a two-thumb range slider powered by the `PhiaRangeSlider` JS hook.

The hook keeps the `--from` and `--to` CSS custom properties on the container
in sync with the thumb positions to drive the filled track segment. It also
sends a `range-change` push event with `{from, to}` on every change.

## Example

    <.range_slider
      id="price-range"
      name_from="price_min"
      name_to="price_max"
      min={0}
      max={1000}
      step={10}
      value_from={@price_min}
      value_to={@price_max}
    />

## Attributes

* `id` (`:string`) (required) - Required for phx-hook.
* `name_from` (`:string`) - Input name for the lower thumb value. Defaults to `nil`.
* `name_to` (`:string`) - Input name for the upper thumb value. Defaults to `nil`.
* `min` (`:integer`) - Defaults to `0`.
* `max` (`:integer`) - Defaults to `100`.
* `step` (`:integer`) - Defaults to `1`.
* `value_from` (`:integer`) - Initial lower thumb value. Defaults to `20`.
* `value_to` (`:integer`) - Initial upper thumb value. Defaults to `80`.
* `show_values` (`:boolean`) - Show current from/to values below slider. Defaults to `true`.
* `disabled` (`:boolean`) - Defaults to `false`.
* `class` (`:string`) - Defaults to `nil`.

# `signature_pad`

Renders a canvas-based freehand signature pad powered by the `PhiaSignaturePad` hook.

On every pointer-up, the hook serializes the canvas to a PNG data URL and sends
a `signature-change` push event with `%{data: "data:image/png;base64,..."}`.
The hidden input (`data-signature-value`) is also updated for native form submission.

## Example

    <.signature_pad id="sig" name="signature" width={500} height={200} />

## Attributes

* `id` (`:string`) (required) - Required for phx-hook.
* `name` (`:string`) - Hidden input name for data URL submission. Defaults to `nil`.
* `width` (`:integer`) - Defaults to `400`.
* `height` (`:integer`) - Defaults to `200`.
* `stroke_color` (`:string`) - Defaults to `"#000000"`.
* `clearable` (`:boolean`) - Show a Clear button below the canvas. Defaults to `true`.
* `class` (`:string`) - Defaults to `nil`.

---

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