# `PhoenixKit.Users.FormatCountry`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v2.64.1/lib/phoenix_kit/users/format_country.ex#L1)

Which country's formats a user reads: `resolve/1`.

The first of these that names a country `BeamLabCountries` knows:

  1. the user's own `country` (a person's, or a company account's own);
  2. the `country` of the company the user belongs to (`organization_uuid`);
  3. the `registration_country` the account signed up from;
  4. the site default, Settings → General → `format_country`.

`nil` means nothing names one, and callers fall back to what they used before
(for dates, the site-wide `date_format` setting).

## The viewer

A page is written for whoever looks at it. Mounting or refreshing the scope
sets the viewer (`put_viewer/1`); their country is resolved on first use and
kept in the process dictionary, as the Gettext locale is. A site-default
fallback follows the settings cache rather than being kept for the session. `PhoenixKit.Utils.Date` reads
it (`viewer/0`) so every date a page prints follows the viewer without the
caller passing anything. With no viewer set (a background job, a signed-out
visitor) `viewer/0` is the site default.

The functions of `PhoenixKit.Utils.Date` that take a user ask `for_user/1`
instead: the user given is the one whose format is wanted, not the one in the
process. A viewer's own record reuses the answer already resolved for them.

A host that renders for someone other than the process's viewer calls
`for_user/1` and passes the code on; it never has to touch the process
dictionary.

# `clear_viewer`

```elixir
@spec clear_viewer() :: :ok
```

Forgets the viewer, so `viewer/0` is the site default again.

# `for_user`

```elixir
@spec for_user(PhoenixKit.Users.Auth.User.t() | term()) :: String.t() | nil
```

`resolve/1` for a user that is not necessarily the viewer: the viewer's own
record reuses the country already resolved for the process.

# `normalize`

```elixir
@spec normalize(term()) :: String.t() | nil
```

`code` as the upper-case alpha-2 code of a country `BeamLabCountries` knows,
else `nil`. Blank, a name instead of a code, a retired or made-up code are
all `nil`: a bad value in one source must not stop the next from being tried.

# `put_viewer`

```elixir
@spec put_viewer(PhoenixKit.Users.Auth.User.t() | nil) :: :ok
```

Sets the viewer of this process. Called when a scope is mounted and again after
the viewer saves their profile.

The country is not looked up here: most requests never print a date, and the
company lookup is a query. `viewer/0` resolves it the first time it is asked.

# `resolve`

```elixir
@spec resolve(PhoenixKit.Users.Auth.User.t() | term()) :: String.t() | nil
```

The country whose formats `user` reads, as an upper-case alpha-2 code, or
`nil`. A `nil` user (nobody signed in), or anything that is not a user row, gets the site default.

# `site_default`

```elixir
@spec site_default() :: String.t() | nil
```

The site default country (Settings → General), or `nil` when none is chosen.
Read from the settings cache.

# `viewer`

```elixir
@spec viewer() :: String.t() | nil
```

The viewer's country: what `put_viewer/1` named, or the site default when
nobody was set for this process. Only the user's country sources are memoized;
the site default is read from the settings cache so a settings change applies
to an already-mounted viewer too.

---

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