# `Localize.Inputs.Number.Unit`
[🔗](https://github.com/elixir-localize/localize_number_inputs/blob/v0.1.1/lib/localize/inputs/number/unit.ex#L1)

Locale-derived display data for unit form inputs.

Mirrors `Localize.Inputs.Number.Symbols` but for the unit picker —
resolves the locale's measurement system, the preferred unit
list for a category in that system, and the full list of all
known units in the category. Unit display names are localized
via `Localize.Unit.display_name/2`.

Categories come from `Localize.Unit.known_categories/0` (e.g.
`"length"`, `"volume"`, `"mass"`). The preferred-by-system map
is a curated table per category — see `@preferred_by_system`
— because CLDR's per-region preference data is keyed by *usage*
(`:person_height`, `:road`, …) and value magnitude, not by a
simple "units that belong to system X" predicate. The curated
table covers the common categories; for everything else
`preferred_units/2` falls back to the full category list.

Prefixed units (SI prefixes like `decimeter`, `kilo*`, etc.)
are filtered out by default — see `:include_prefixed`.

# `t`

```elixir
@type t() :: %Localize.Inputs.Number.Unit{
  all_units: [{String.t(), String.t()}],
  category: String.t(),
  language_tag: Localize.LanguageTag.t(),
  locale: atom(),
  measurement_system: atom(),
  preferred_units: [{String.t(), String.t()}],
  unit: String.t() | nil,
  unit_display_name: String.t() | nil
}
```

Locale display data resolved by `unit_for_locale/2`.

* `:locale` — the canonical CLDR locale id (atom).

* `:language_tag` — the full `t:Localize.LanguageTag.t/0`.

* `:category` — the unit category as a string (e.g. `"length"`).

* `:measurement_system` — the locale's default measurement
  system as an atom (`:metric`, `:us`, `:uk`).

* `:unit` — the selected unit name as a string, or `nil` if
  the caller didn't specify one.

* `:unit_display_name` — the localized display name of the
  selected unit, or `nil`.

* `:preferred_units` — list of `{name, display_name}` tuples,
  the units in this category that belong to the locale's
  measurement system. Sorted in roughly small-to-large order
  where the curated table provides it; alphabetical otherwise.

* `:all_units` — list of `{name, display_name}` tuples, every
  known unit in the category. Alphabetical by name.

# `all_unit_names`

```elixir
@spec all_unit_names(String.t(), boolean()) :: [String.t()]
```

Returns every known unit name in the given category.

### Arguments

* `category` — a category string from `known_categories/0`.

* `include_prefixed` — when `true`, includes SI-prefixed
  variants (e.g. `decimeter`, `kilogram-square-meter`). The
  default is `false`.

# `known_categories`

```elixir
@spec known_categories() :: [String.t()]
```

Returns the list of unit categories known to CLDR.

### Returns

* A list of strings such as `["acceleration", "angle", "area", "length", "mass", ...]`.

# `preferred_unit_names`

```elixir
@spec preferred_unit_names(String.t(), atom()) :: [String.t()]
```

Returns the curated preferred-unit names for the given
`(category, system)` pair, or the full category list if no
curation exists for that pair.

### Returns

* A list of unit name strings.

# `unit_for_locale`

```elixir
@spec unit_for_locale(
  Localize.LanguageTag.t() | atom() | String.t() | nil,
  Keyword.t()
) ::
  {:ok, t()} | {:error, Exception.t()}
```

Resolves picker display data for the given locale + category.

### Arguments

* `locale` is a locale identifier (atom, string, or
  `t:Localize.LanguageTag.t/0`). Defaults to
  `Localize.get_locale/0`.

* `options` is a keyword list of options.

### Options

* `:category` is a unit category string from
  `Localize.Unit.known_categories/0` (e.g. `"length"`).
  **Required.**

* `:unit` is a specific unit name to also resolve display data
  for. Optional.

* `:include_prefixed` — when `true`, SI-prefixed unit variants
  (e.g. `decimeter`, `kilogram-square-meter`) are included in
  the `:all_units` list. The default is `false` to keep
  pickers manageable. The curated preferred lists are always
  used as-is.

### Returns

* `{:ok, t()}` on success.

* `{:error, Exception.t()}` when the locale can't be parsed
  (`Localize.InvalidLocaleError`) or the category is unknown.

### Examples

    iex> {:ok, info} = Localize.Inputs.Number.Unit.unit_for_locale(:en, category: "length")
    iex> info.measurement_system
    :us

    iex> {:ok, info} = Localize.Inputs.Number.Unit.unit_for_locale(:fr, category: "length")
    iex> info.measurement_system
    :metric

    iex> {:ok, info} = Localize.Inputs.Number.Unit.unit_for_locale(:en, category: "length", unit: "meter")
    iex> info.unit
    "meter"

---

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