# `Koyomi.Components`
[🔗](https://github.com/hattoriai/koyomi/blob/v0.2.1/lib/koyomi/components.ex#L1)

Function components for the Koyomi pickers.

    import Koyomi.Components

    <.form for={@form} phx-change="validate" phx-submit="save">
      <label id="due-label">Due</label>
      <.date_picker field={@form[:due]} label_id="due-label" min={:today} />

      <label id="stay-label">Stay</label>
      <.date_range_picker field={@form[:stay]} label_id="stay-label" months={2} />
    </.form>

The pickers need the `Koyomi` hook in the LiveSocket and the Koyomi CSS
(see the README). Each picker is a field for a form: it posts its value
with the form, in the form of the browser's own inputs (`2027-03-15`,
`2027-03`, `2027-W11`, `14:30:00`), so the form's own `phx-change` and
`phx-submit` events have it, and the Ecto types of the field cast it.

Before the hook mounts (and with JavaScript off), the picker is the
browser's own input of its kind, with the same name and value.

## The pickers

  * `date_picker/1` - a day (`:date`).
  * `date_range_picker/1` - a range of days (`Koyomi.DateRange`, or two
    `:date` fields).
  * `dates_picker/1` - several days (`Koyomi.Dates`).
  * `month_picker/1`, `year_picker/1`, `week_picker/1` - a month
    (`Koyomi.Month`), a year (`:integer`), an ISO week (`Koyomi.Week`).
  * `time_picker/1` - a time of day (`:time`).
  * `datetime_picker/1` - a day and a time (`:utc_datetime` with a
    `time_zone`, else `:naive_datetime`), from a free choice or from the
    time slots that the LiveView offers.
  * `recurrence_picker/1` - a repeat rule (`Koyomi.Recurrence`).
  * `calendar/1` - a calendar on the page, to show days and to pick one
    or more outside a form.

Every picker has the attributes below (the shared ones); the docs of
each picker list its own.

# `calendar`

Renders a calendar on the page, with no field: to show days and their
content, and to pick a day, a range or several days outside a form.

With `select`, a click picks, and the picker pushes `on_change` with the
value. With a `name`, it also posts the value with a form.

## Attributes

* `field` (`Phoenix.HTML.FormField`) - the form field, for example `@form[:due]`. Defaults to `nil`.
* `id` (`:string`) - the id of the picker element; the default is the field's id with `_picker`. Defaults to `nil`.
* `name` (`:string`) - the input name, without a `field`. Defaults to `nil`.
* `value` (`:any`) - the value, without a `field`. Defaults to `nil`.
* `label_id` (`:string`) - the id of the element that labels the picker (`aria-labelledby`); without it, the picker gets `aria-label` from `label`. Defaults to `nil`.
* `label` (`:string`) - the accessible name when there is no `label_id`; the default is the field name in words. Defaults to `nil`.
* `rules` (`:any`) - the rules of the picker, a `Koyomi.Rules` or its options; give the same to `Koyomi.Changeset`. Defaults to `nil`.
* `min` (`:any`) - a shortcut for the `:min` rule. Defaults to `nil`.
* `max` (`:any`) - a shortcut for the `:max` rule. Defaults to `nil`.
* `locale` (`:string`) - a BCP 47 locale for names, numbers, the order of the fields and the first day of the week; the default is `config :koyomi, locale:`, else "en". Defaults to `nil`.
* `calendar` (`:string`) - the calendar system of the display: the locale's own (`-u-ca-`), else `gregory`; or `japanese`, `buddhist`, `islamic-umalqura`, `hebrew`, `persian`, ... (see the Calendars guide). Defaults to `nil`.
* `time_zone` (`:string`) - the IANA time zone of today and, for a date and time picker, of the wall clock; the default is UTC. Defaults to `nil`.
* `first_day` (`:integer`) - the first day of the week, ISO (1 is Monday, 7 is Sunday); the default is the locale's. Defaults to `nil`.
* `presets` (`:list`) - the presets beside the calendar, see `Koyomi.Presets`. Defaults to `nil`.
* `holidays` (`:any`) - public holidays to mark: a country code ("PT"), a `Koyomi.Holidays.Provider` module, or a list of them. Defaults to `nil`.
* `days` (`:boolean`) - when `true`, the picker asks the LiveView for the content of the days it shows (`koyomi:days`), see the Day content guide. Defaults to `false`.
* `inline` (`:boolean`) - when `true`, the calendar is always shown, with no field and no popover. Defaults to `false`.
* `months` (`:integer`) - the months shown side by side. Defaults to `1`.
* `week_numbers` (`:boolean`) - when `true`, the calendar shows ISO week numbers. Defaults to `false`.
* `outside_days` (`:boolean`) - when `false`, the days of the previous and next months are left blank. Defaults to `true`.
* `typing` (`:boolean`) - when `false`, the popover has no box for typing a date in words. Defaults to `true`.
* `clearable` (`:boolean`) - when `true`, the field has a clear button; the default is `true` unless `required`. Defaults to `nil`.
* `required` (`:boolean`) - Defaults to `false`.
* `disabled` (`:boolean`) - Defaults to `false`.
* `readonly` (`:boolean`) - Defaults to `false`.
* `display` (`:string`) - the length of the dates that the picker writes out (`Intl` `dateStyle`). Defaults to `"medium"`. Must be one of `"short"`, `"medium"`, `"long"`, or `"full"`.
* `on_change` (`:string`) - an event that the picker pushes with `%{"id", "value"}` on each change, for a picker outside a form. Defaults to `nil`.
* `messages` (`:map`) - words that replace the built-in ones, see `Koyomi.Messages`. Defaults to `nil`.
* `class` (`:any`) - classes for the picker element. Defaults to `nil`.
* `select` (`:string`) - what a click picks; nothing by default. Defaults to `nil`. Must be one of `nil`, `"date"`, `"range"`, or `"dates"`.
* Global attributes are accepted. attributes for the picker element, such as `phx-target`; `aria-describedby` goes to the field. Supports all globals plus: `["form"]`.

# `date_picker`

Renders a date picker: a field with a segment for each part of the date
(typed, or changed with the arrow keys), and a calendar in a popover.

The value is a `Date`; the picker posts `YYYY-MM-DD`, and nothing (an
empty string) when it is cleared.

With `relative`, a preset that a person chooses posts its key
(`"tomorrow"`, `"in_1_week"`) instead of its day, and a key as the value
shows that preset: for filters and URLs that keep "today" meaning today
(see the [Filters and URLs](filters.md) guide).

## Attributes

* `field` (`Phoenix.HTML.FormField`) - the form field, for example `@form[:due]`. Defaults to `nil`.
* `id` (`:string`) - the id of the picker element; the default is the field's id with `_picker`. Defaults to `nil`.
* `name` (`:string`) - the input name, without a `field`. Defaults to `nil`.
* `value` (`:any`) - the value, without a `field`. Defaults to `nil`.
* `label_id` (`:string`) - the id of the element that labels the picker (`aria-labelledby`); without it, the picker gets `aria-label` from `label`. Defaults to `nil`.
* `label` (`:string`) - the accessible name when there is no `label_id`; the default is the field name in words. Defaults to `nil`.
* `rules` (`:any`) - the rules of the picker, a `Koyomi.Rules` or its options; give the same to `Koyomi.Changeset`. Defaults to `nil`.
* `min` (`:any`) - a shortcut for the `:min` rule. Defaults to `nil`.
* `max` (`:any`) - a shortcut for the `:max` rule. Defaults to `nil`.
* `locale` (`:string`) - a BCP 47 locale for names, numbers, the order of the fields and the first day of the week; the default is `config :koyomi, locale:`, else "en". Defaults to `nil`.
* `calendar` (`:string`) - the calendar system of the display: the locale's own (`-u-ca-`), else `gregory`; or `japanese`, `buddhist`, `islamic-umalqura`, `hebrew`, `persian`, ... (see the Calendars guide). Defaults to `nil`.
* `time_zone` (`:string`) - the IANA time zone of today and, for a date and time picker, of the wall clock; the default is UTC. Defaults to `nil`.
* `first_day` (`:integer`) - the first day of the week, ISO (1 is Monday, 7 is Sunday); the default is the locale's. Defaults to `nil`.
* `presets` (`:list`) - the presets beside the calendar, see `Koyomi.Presets`. Defaults to `nil`.
* `holidays` (`:any`) - public holidays to mark: a country code ("PT"), a `Koyomi.Holidays.Provider` module, or a list of them. Defaults to `nil`.
* `days` (`:boolean`) - when `true`, the picker asks the LiveView for the content of the days it shows (`koyomi:days`), see the Day content guide. Defaults to `false`.
* `inline` (`:boolean`) - when `true`, the calendar is always shown, with no field and no popover. Defaults to `false`.
* `months` (`:integer`) - the months shown side by side. Defaults to `1`.
* `week_numbers` (`:boolean`) - when `true`, the calendar shows ISO week numbers. Defaults to `false`.
* `outside_days` (`:boolean`) - when `false`, the days of the previous and next months are left blank. Defaults to `true`.
* `typing` (`:boolean`) - when `false`, the popover has no box for typing a date in words. Defaults to `true`.
* `clearable` (`:boolean`) - when `true`, the field has a clear button; the default is `true` unless `required`. Defaults to `nil`.
* `required` (`:boolean`) - Defaults to `false`.
* `disabled` (`:boolean`) - Defaults to `false`.
* `readonly` (`:boolean`) - Defaults to `false`.
* `display` (`:string`) - the length of the dates that the picker writes out (`Intl` `dateStyle`). Defaults to `"medium"`. Must be one of `"short"`, `"medium"`, `"long"`, or `"full"`.
* `on_change` (`:string`) - an event that the picker pushes with `%{"id", "value"}` on each change, for a picker outside a form. Defaults to `nil`.
* `messages` (`:map`) - words that replace the built-in ones, see `Koyomi.Messages`. Defaults to `nil`.
* `class` (`:any`) - classes for the picker element. Defaults to `nil`.
* `relative` (`:boolean`) - when `true`, a chosen preset posts its key instead of its day, see `Koyomi.Presets`. Defaults to `false`.
* Global attributes are accepted. attributes for the picker element, such as `phx-target`; `aria-describedby` goes to the field. Supports all globals plus: `["form"]`.

# `date_range_picker`

Renders a date range picker: a field with the first and the last day,
and a calendar where the first click starts the range and the second
ends it, with the range drawn as the pointer moves.

Give it one field of the `Koyomi.DateRange` type (`field`), which it
posts as `field[from]` and `field[to]` (or with the names of `keys`), or
two `:date` fields (`from` and `to`), which it posts as they are. With a
`name` and no field, as in a filter, the value is a map with those keys,
as the params have it.

With `relative`, a preset that a person chooses posts its key
(`field=last_7_days`) instead of `field[from]` and `field[to]`, and a key
as the value shows that preset (see the [Filters and URLs](filters.md)
guide). It posts only whole ranges: while one
end is chosen, the form keeps the previous value.

The rules `:min_days`, `:max_days` and `:allow_disabled_in_range` apply
to the range; days that the range could not reach from its first day
are disabled while the second is chosen.

## Attributes

* `field` (`Phoenix.HTML.FormField`) - the form field, for example `@form[:due]`. Defaults to `nil`.
* `id` (`:string`) - the id of the picker element; the default is the field's id with `_picker`. Defaults to `nil`.
* `name` (`:string`) - the input name, without a `field`. Defaults to `nil`.
* `value` (`:any`) - the value, without a `field`. Defaults to `nil`.
* `label_id` (`:string`) - the id of the element that labels the picker (`aria-labelledby`); without it, the picker gets `aria-label` from `label`. Defaults to `nil`.
* `label` (`:string`) - the accessible name when there is no `label_id`; the default is the field name in words. Defaults to `nil`.
* `rules` (`:any`) - the rules of the picker, a `Koyomi.Rules` or its options; give the same to `Koyomi.Changeset`. Defaults to `nil`.
* `min` (`:any`) - a shortcut for the `:min` rule. Defaults to `nil`.
* `max` (`:any`) - a shortcut for the `:max` rule. Defaults to `nil`.
* `locale` (`:string`) - a BCP 47 locale for names, numbers, the order of the fields and the first day of the week; the default is `config :koyomi, locale:`, else "en". Defaults to `nil`.
* `calendar` (`:string`) - the calendar system of the display: the locale's own (`-u-ca-`), else `gregory`; or `japanese`, `buddhist`, `islamic-umalqura`, `hebrew`, `persian`, ... (see the Calendars guide). Defaults to `nil`.
* `time_zone` (`:string`) - the IANA time zone of today and, for a date and time picker, of the wall clock; the default is UTC. Defaults to `nil`.
* `first_day` (`:integer`) - the first day of the week, ISO (1 is Monday, 7 is Sunday); the default is the locale's. Defaults to `nil`.
* `presets` (`:list`) - the presets beside the calendar, see `Koyomi.Presets`. Defaults to `nil`.
* `holidays` (`:any`) - public holidays to mark: a country code ("PT"), a `Koyomi.Holidays.Provider` module, or a list of them. Defaults to `nil`.
* `days` (`:boolean`) - when `true`, the picker asks the LiveView for the content of the days it shows (`koyomi:days`), see the Day content guide. Defaults to `false`.
* `inline` (`:boolean`) - when `true`, the calendar is always shown, with no field and no popover. Defaults to `false`.
* `months` (`:integer`) - the months shown side by side. Defaults to `1`.
* `week_numbers` (`:boolean`) - when `true`, the calendar shows ISO week numbers. Defaults to `false`.
* `outside_days` (`:boolean`) - when `false`, the days of the previous and next months are left blank. Defaults to `true`.
* `typing` (`:boolean`) - when `false`, the popover has no box for typing a date in words. Defaults to `true`.
* `clearable` (`:boolean`) - when `true`, the field has a clear button; the default is `true` unless `required`. Defaults to `nil`.
* `required` (`:boolean`) - Defaults to `false`.
* `disabled` (`:boolean`) - Defaults to `false`.
* `readonly` (`:boolean`) - Defaults to `false`.
* `display` (`:string`) - the length of the dates that the picker writes out (`Intl` `dateStyle`). Defaults to `"medium"`. Must be one of `"short"`, `"medium"`, `"long"`, or `"full"`.
* `on_change` (`:string`) - an event that the picker pushes with `%{"id", "value"}` on each change, for a picker outside a form. Defaults to `nil`.
* `messages` (`:map`) - words that replace the built-in ones, see `Koyomi.Messages`. Defaults to `nil`.
* `class` (`:any`) - classes for the picker element. Defaults to `nil`.
* `from` (`Phoenix.HTML.FormField`) - the field of the first day, with `to`. Defaults to `nil`.
* `to` (`Phoenix.HTML.FormField`) - the field of the last day, with `from`. Defaults to `nil`.
* `keys` (`:any`) - the keys of the two days in the posted map and in the value: `{"start", "end"}` posts `field[start]` and `field[end]`. Defaults to `{"from", "to"}`.
* `relative` (`:boolean`) - when `true`, a chosen preset posts its key (`"last_7_days"`) instead of its days, see `Koyomi.Presets`. Defaults to `false`.
* `nights` (`:boolean`) - when `true`, the picker counts nights (days minus one), as for a stay. Defaults to `false`.
* Global attributes are accepted. attributes for the picker element, such as `phx-target`; `aria-describedby` goes to the field. Supports all globals plus: `["form"]`.

# `dates_picker`

Renders a picker of several days, each added or removed with a click,
and listed in the field.

The value is a list of `Date`; the picker posts `field[]` for each day,
after an empty first entry, so that a form with no day still posts the
field (see `Koyomi.Dates`). The rules `:min_count` and `:max_count`
apply.

## Attributes

* `field` (`Phoenix.HTML.FormField`) - the form field, for example `@form[:due]`. Defaults to `nil`.
* `id` (`:string`) - the id of the picker element; the default is the field's id with `_picker`. Defaults to `nil`.
* `name` (`:string`) - the input name, without a `field`. Defaults to `nil`.
* `value` (`:any`) - the value, without a `field`. Defaults to `nil`.
* `label_id` (`:string`) - the id of the element that labels the picker (`aria-labelledby`); without it, the picker gets `aria-label` from `label`. Defaults to `nil`.
* `label` (`:string`) - the accessible name when there is no `label_id`; the default is the field name in words. Defaults to `nil`.
* `rules` (`:any`) - the rules of the picker, a `Koyomi.Rules` or its options; give the same to `Koyomi.Changeset`. Defaults to `nil`.
* `min` (`:any`) - a shortcut for the `:min` rule. Defaults to `nil`.
* `max` (`:any`) - a shortcut for the `:max` rule. Defaults to `nil`.
* `locale` (`:string`) - a BCP 47 locale for names, numbers, the order of the fields and the first day of the week; the default is `config :koyomi, locale:`, else "en". Defaults to `nil`.
* `calendar` (`:string`) - the calendar system of the display: the locale's own (`-u-ca-`), else `gregory`; or `japanese`, `buddhist`, `islamic-umalqura`, `hebrew`, `persian`, ... (see the Calendars guide). Defaults to `nil`.
* `time_zone` (`:string`) - the IANA time zone of today and, for a date and time picker, of the wall clock; the default is UTC. Defaults to `nil`.
* `first_day` (`:integer`) - the first day of the week, ISO (1 is Monday, 7 is Sunday); the default is the locale's. Defaults to `nil`.
* `presets` (`:list`) - the presets beside the calendar, see `Koyomi.Presets`. Defaults to `nil`.
* `holidays` (`:any`) - public holidays to mark: a country code ("PT"), a `Koyomi.Holidays.Provider` module, or a list of them. Defaults to `nil`.
* `days` (`:boolean`) - when `true`, the picker asks the LiveView for the content of the days it shows (`koyomi:days`), see the Day content guide. Defaults to `false`.
* `inline` (`:boolean`) - when `true`, the calendar is always shown, with no field and no popover. Defaults to `false`.
* `months` (`:integer`) - the months shown side by side. Defaults to `1`.
* `week_numbers` (`:boolean`) - when `true`, the calendar shows ISO week numbers. Defaults to `false`.
* `outside_days` (`:boolean`) - when `false`, the days of the previous and next months are left blank. Defaults to `true`.
* `typing` (`:boolean`) - when `false`, the popover has no box for typing a date in words. Defaults to `true`.
* `clearable` (`:boolean`) - when `true`, the field has a clear button; the default is `true` unless `required`. Defaults to `nil`.
* `required` (`:boolean`) - Defaults to `false`.
* `disabled` (`:boolean`) - Defaults to `false`.
* `readonly` (`:boolean`) - Defaults to `false`.
* `display` (`:string`) - the length of the dates that the picker writes out (`Intl` `dateStyle`). Defaults to `"medium"`. Must be one of `"short"`, `"medium"`, `"long"`, or `"full"`.
* `on_change` (`:string`) - an event that the picker pushes with `%{"id", "value"}` on each change, for a picker outside a form. Defaults to `nil`.
* `messages` (`:map`) - words that replace the built-in ones, see `Koyomi.Messages`. Defaults to `nil`.
* `class` (`:any`) - classes for the picker element. Defaults to `nil`.
* Global attributes are accepted. attributes for the picker element, such as `phx-target`; `aria-describedby` goes to the field. Supports all globals plus: `["form"]`.

# `datetime_picker`

Renders a date and time picker: the date field and calendar of
`date_picker/1` with the time field and list of `time_picker/1`.

With a `time_zone`, the person picks a wall clock time in that zone, and
the picker posts it with the zone's offset at that moment
(`2027-03-15T14:30:00+01:00`, or `Z` when the offset is zero), which a
`:utc_datetime` field casts to
UTC; a time that the zone skips or repeats on that day (when the clocks
change) is shown and resolved before it is posted. Without a
`time_zone`, it posts a date and time without an offset, for a
`:naive_datetime` field.

With `slots`, the times come from the LiveView, for the day that is
chosen (the `slots` of the day content, see `Koyomi.Live`), as for a
booking; the calendar then also asks for the days (`days`).

## Attributes

* `field` (`Phoenix.HTML.FormField`) - the form field, for example `@form[:due]`. Defaults to `nil`.
* `id` (`:string`) - the id of the picker element; the default is the field's id with `_picker`. Defaults to `nil`.
* `name` (`:string`) - the input name, without a `field`. Defaults to `nil`.
* `value` (`:any`) - the value, without a `field`. Defaults to `nil`.
* `label_id` (`:string`) - the id of the element that labels the picker (`aria-labelledby`); without it, the picker gets `aria-label` from `label`. Defaults to `nil`.
* `label` (`:string`) - the accessible name when there is no `label_id`; the default is the field name in words. Defaults to `nil`.
* `rules` (`:any`) - the rules of the picker, a `Koyomi.Rules` or its options; give the same to `Koyomi.Changeset`. Defaults to `nil`.
* `min` (`:any`) - a shortcut for the `:min` rule. Defaults to `nil`.
* `max` (`:any`) - a shortcut for the `:max` rule. Defaults to `nil`.
* `locale` (`:string`) - a BCP 47 locale for names, numbers, the order of the fields and the first day of the week; the default is `config :koyomi, locale:`, else "en". Defaults to `nil`.
* `calendar` (`:string`) - the calendar system of the display: the locale's own (`-u-ca-`), else `gregory`; or `japanese`, `buddhist`, `islamic-umalqura`, `hebrew`, `persian`, ... (see the Calendars guide). Defaults to `nil`.
* `time_zone` (`:string`) - the IANA time zone of today and, for a date and time picker, of the wall clock; the default is UTC. Defaults to `nil`.
* `first_day` (`:integer`) - the first day of the week, ISO (1 is Monday, 7 is Sunday); the default is the locale's. Defaults to `nil`.
* `presets` (`:list`) - the presets beside the calendar, see `Koyomi.Presets`. Defaults to `nil`.
* `holidays` (`:any`) - public holidays to mark: a country code ("PT"), a `Koyomi.Holidays.Provider` module, or a list of them. Defaults to `nil`.
* `days` (`:boolean`) - when `true`, the picker asks the LiveView for the content of the days it shows (`koyomi:days`), see the Day content guide. Defaults to `false`.
* `inline` (`:boolean`) - when `true`, the calendar is always shown, with no field and no popover. Defaults to `false`.
* `months` (`:integer`) - the months shown side by side. Defaults to `1`.
* `week_numbers` (`:boolean`) - when `true`, the calendar shows ISO week numbers. Defaults to `false`.
* `outside_days` (`:boolean`) - when `false`, the days of the previous and next months are left blank. Defaults to `true`.
* `typing` (`:boolean`) - when `false`, the popover has no box for typing a date in words. Defaults to `true`.
* `clearable` (`:boolean`) - when `true`, the field has a clear button; the default is `true` unless `required`. Defaults to `nil`.
* `required` (`:boolean`) - Defaults to `false`.
* `disabled` (`:boolean`) - Defaults to `false`.
* `readonly` (`:boolean`) - Defaults to `false`.
* `display` (`:string`) - the length of the dates that the picker writes out (`Intl` `dateStyle`). Defaults to `"medium"`. Must be one of `"short"`, `"medium"`, `"long"`, or `"full"`.
* `on_change` (`:string`) - an event that the picker pushes with `%{"id", "value"}` on each change, for a picker outside a form. Defaults to `nil`.
* `messages` (`:map`) - words that replace the built-in ones, see `Koyomi.Messages`. Defaults to `nil`.
* `class` (`:any`) - classes for the picker element. Defaults to `nil`.
* `seconds` (`:boolean`) - when `true`, the field has seconds. Defaults to `false`.
* `hour_cycle` (`:string`) - the 12 or 24-hour clock; the default is the locale's. Defaults to `nil`. Must be one of `nil`, `"h12"`, or `"h23"`.
* `slots` (`:boolean`) - when `true`, the times of a day are the slots that the LiveView gives. Defaults to `false`.
* `ambiguous` (`:atom`) - the instant of a wall clock time that happens twice (when the clocks go back), until the person picks the other. Defaults to `:earlier`. Must be one of `:earlier`, or `:later`.
* Global attributes are accepted. attributes for the picker element, such as `phx-target`; `aria-describedby` goes to the field. Supports all globals plus: `["form"]`.

# `month_picker`

Renders a month picker: a field with the month and the year, and a grid
of the months of a year. It posts `YYYY-MM`; the `Koyomi.Month` type
stores it as the first day of the month.

## Attributes

* `field` (`Phoenix.HTML.FormField`) - the form field, for example `@form[:due]`. Defaults to `nil`.
* `id` (`:string`) - the id of the picker element; the default is the field's id with `_picker`. Defaults to `nil`.
* `name` (`:string`) - the input name, without a `field`. Defaults to `nil`.
* `value` (`:any`) - the value, without a `field`. Defaults to `nil`.
* `label_id` (`:string`) - the id of the element that labels the picker (`aria-labelledby`); without it, the picker gets `aria-label` from `label`. Defaults to `nil`.
* `label` (`:string`) - the accessible name when there is no `label_id`; the default is the field name in words. Defaults to `nil`.
* `rules` (`:any`) - the rules of the picker, a `Koyomi.Rules` or its options; give the same to `Koyomi.Changeset`. Defaults to `nil`.
* `min` (`:any`) - a shortcut for the `:min` rule. Defaults to `nil`.
* `max` (`:any`) - a shortcut for the `:max` rule. Defaults to `nil`.
* `locale` (`:string`) - a BCP 47 locale for names, numbers, the order of the fields and the first day of the week; the default is `config :koyomi, locale:`, else "en". Defaults to `nil`.
* `calendar` (`:string`) - the calendar system of the display: the locale's own (`-u-ca-`), else `gregory`; or `japanese`, `buddhist`, `islamic-umalqura`, `hebrew`, `persian`, ... (see the Calendars guide). Defaults to `nil`.
* `time_zone` (`:string`) - the IANA time zone of today and, for a date and time picker, of the wall clock; the default is UTC. Defaults to `nil`.
* `first_day` (`:integer`) - the first day of the week, ISO (1 is Monday, 7 is Sunday); the default is the locale's. Defaults to `nil`.
* `presets` (`:list`) - the presets beside the calendar, see `Koyomi.Presets`. Defaults to `nil`.
* `holidays` (`:any`) - public holidays to mark: a country code ("PT"), a `Koyomi.Holidays.Provider` module, or a list of them. Defaults to `nil`.
* `days` (`:boolean`) - when `true`, the picker asks the LiveView for the content of the days it shows (`koyomi:days`), see the Day content guide. Defaults to `false`.
* `inline` (`:boolean`) - when `true`, the calendar is always shown, with no field and no popover. Defaults to `false`.
* `months` (`:integer`) - the months shown side by side. Defaults to `1`.
* `week_numbers` (`:boolean`) - when `true`, the calendar shows ISO week numbers. Defaults to `false`.
* `outside_days` (`:boolean`) - when `false`, the days of the previous and next months are left blank. Defaults to `true`.
* `typing` (`:boolean`) - when `false`, the popover has no box for typing a date in words. Defaults to `true`.
* `clearable` (`:boolean`) - when `true`, the field has a clear button; the default is `true` unless `required`. Defaults to `nil`.
* `required` (`:boolean`) - Defaults to `false`.
* `disabled` (`:boolean`) - Defaults to `false`.
* `readonly` (`:boolean`) - Defaults to `false`.
* `display` (`:string`) - the length of the dates that the picker writes out (`Intl` `dateStyle`). Defaults to `"medium"`. Must be one of `"short"`, `"medium"`, `"long"`, or `"full"`.
* `on_change` (`:string`) - an event that the picker pushes with `%{"id", "value"}` on each change, for a picker outside a form. Defaults to `nil`.
* `messages` (`:map`) - words that replace the built-in ones, see `Koyomi.Messages`. Defaults to `nil`.
* `class` (`:any`) - classes for the picker element. Defaults to `nil`.
* Global attributes are accepted. attributes for the picker element, such as `phx-target`; `aria-describedby` goes to the field. Supports all globals plus: `["form"]`.

# `recurrence_picker`

Renders a recurrence picker: how often something repeats (every day,
week, month or year, every so many), on which days, and until when,
with a sentence that says it and the next dates.

It posts an RFC 5545 rule (`FREQ=WEEKLY;BYDAY=MO,WE`), or nothing for
"does not repeat"; the `Koyomi.Recurrence` type casts it.

## Attributes

* `field` (`Phoenix.HTML.FormField`) - the form field, for example `@form[:due]`. Defaults to `nil`.
* `id` (`:string`) - the id of the picker element; the default is the field's id with `_picker`. Defaults to `nil`.
* `name` (`:string`) - the input name, without a `field`. Defaults to `nil`.
* `value` (`:any`) - the value, without a `field`. Defaults to `nil`.
* `label_id` (`:string`) - the id of the element that labels the picker (`aria-labelledby`); without it, the picker gets `aria-label` from `label`. Defaults to `nil`.
* `label` (`:string`) - the accessible name when there is no `label_id`; the default is the field name in words. Defaults to `nil`.
* `rules` (`:any`) - the rules of the picker, a `Koyomi.Rules` or its options; give the same to `Koyomi.Changeset`. Defaults to `nil`.
* `min` (`:any`) - a shortcut for the `:min` rule. Defaults to `nil`.
* `max` (`:any`) - a shortcut for the `:max` rule. Defaults to `nil`.
* `locale` (`:string`) - a BCP 47 locale for names, numbers, the order of the fields and the first day of the week; the default is `config :koyomi, locale:`, else "en". Defaults to `nil`.
* `calendar` (`:string`) - the calendar system of the display: the locale's own (`-u-ca-`), else `gregory`; or `japanese`, `buddhist`, `islamic-umalqura`, `hebrew`, `persian`, ... (see the Calendars guide). Defaults to `nil`.
* `time_zone` (`:string`) - the IANA time zone of today and, for a date and time picker, of the wall clock; the default is UTC. Defaults to `nil`.
* `first_day` (`:integer`) - the first day of the week, ISO (1 is Monday, 7 is Sunday); the default is the locale's. Defaults to `nil`.
* `presets` (`:list`) - the presets beside the calendar, see `Koyomi.Presets`. Defaults to `nil`.
* `holidays` (`:any`) - public holidays to mark: a country code ("PT"), a `Koyomi.Holidays.Provider` module, or a list of them. Defaults to `nil`.
* `days` (`:boolean`) - when `true`, the picker asks the LiveView for the content of the days it shows (`koyomi:days`), see the Day content guide. Defaults to `false`.
* `inline` (`:boolean`) - when `true`, the calendar is always shown, with no field and no popover. Defaults to `false`.
* `months` (`:integer`) - the months shown side by side. Defaults to `1`.
* `week_numbers` (`:boolean`) - when `true`, the calendar shows ISO week numbers. Defaults to `false`.
* `outside_days` (`:boolean`) - when `false`, the days of the previous and next months are left blank. Defaults to `true`.
* `typing` (`:boolean`) - when `false`, the popover has no box for typing a date in words. Defaults to `true`.
* `clearable` (`:boolean`) - when `true`, the field has a clear button; the default is `true` unless `required`. Defaults to `nil`.
* `required` (`:boolean`) - Defaults to `false`.
* `disabled` (`:boolean`) - Defaults to `false`.
* `readonly` (`:boolean`) - Defaults to `false`.
* `display` (`:string`) - the length of the dates that the picker writes out (`Intl` `dateStyle`). Defaults to `"medium"`. Must be one of `"short"`, `"medium"`, `"long"`, or `"full"`.
* `on_change` (`:string`) - an event that the picker pushes with `%{"id", "value"}` on each change, for a picker outside a form. Defaults to `nil`.
* `messages` (`:map`) - words that replace the built-in ones, see `Koyomi.Messages`. Defaults to `nil`.
* `class` (`:any`) - classes for the picker element. Defaults to `nil`.
* `start` (`:any`) - the first occurrence (a `Date` or a `DateTime`), for the days and the next dates; today by default. Defaults to `nil`.
* Global attributes are accepted. attributes for the picker element, such as `phx-target`; `aria-describedby` goes to the field. Supports all globals plus: `["form"]`.

# `time_picker`

Renders a time picker: a field with the hour, the minutes (and the
seconds with `seconds`), in the 12 or 24-hour clock of the locale, and a
list of times in a popover.

It posts `HH:MM:SS`. The rules `:min_time`, `:max_time` and `:step`
apply; `step` is also the step of the list (30 minutes when not given).

## Attributes

* `field` (`Phoenix.HTML.FormField`) - the form field, for example `@form[:due]`. Defaults to `nil`.
* `id` (`:string`) - the id of the picker element; the default is the field's id with `_picker`. Defaults to `nil`.
* `name` (`:string`) - the input name, without a `field`. Defaults to `nil`.
* `value` (`:any`) - the value, without a `field`. Defaults to `nil`.
* `label_id` (`:string`) - the id of the element that labels the picker (`aria-labelledby`); without it, the picker gets `aria-label` from `label`. Defaults to `nil`.
* `label` (`:string`) - the accessible name when there is no `label_id`; the default is the field name in words. Defaults to `nil`.
* `rules` (`:any`) - the rules of the picker, a `Koyomi.Rules` or its options; give the same to `Koyomi.Changeset`. Defaults to `nil`.
* `min` (`:any`) - a shortcut for the `:min` rule. Defaults to `nil`.
* `max` (`:any`) - a shortcut for the `:max` rule. Defaults to `nil`.
* `locale` (`:string`) - a BCP 47 locale for names, numbers, the order of the fields and the first day of the week; the default is `config :koyomi, locale:`, else "en". Defaults to `nil`.
* `calendar` (`:string`) - the calendar system of the display: the locale's own (`-u-ca-`), else `gregory`; or `japanese`, `buddhist`, `islamic-umalqura`, `hebrew`, `persian`, ... (see the Calendars guide). Defaults to `nil`.
* `time_zone` (`:string`) - the IANA time zone of today and, for a date and time picker, of the wall clock; the default is UTC. Defaults to `nil`.
* `first_day` (`:integer`) - the first day of the week, ISO (1 is Monday, 7 is Sunday); the default is the locale's. Defaults to `nil`.
* `presets` (`:list`) - the presets beside the calendar, see `Koyomi.Presets`. Defaults to `nil`.
* `holidays` (`:any`) - public holidays to mark: a country code ("PT"), a `Koyomi.Holidays.Provider` module, or a list of them. Defaults to `nil`.
* `days` (`:boolean`) - when `true`, the picker asks the LiveView for the content of the days it shows (`koyomi:days`), see the Day content guide. Defaults to `false`.
* `inline` (`:boolean`) - when `true`, the calendar is always shown, with no field and no popover. Defaults to `false`.
* `months` (`:integer`) - the months shown side by side. Defaults to `1`.
* `week_numbers` (`:boolean`) - when `true`, the calendar shows ISO week numbers. Defaults to `false`.
* `outside_days` (`:boolean`) - when `false`, the days of the previous and next months are left blank. Defaults to `true`.
* `typing` (`:boolean`) - when `false`, the popover has no box for typing a date in words. Defaults to `true`.
* `clearable` (`:boolean`) - when `true`, the field has a clear button; the default is `true` unless `required`. Defaults to `nil`.
* `required` (`:boolean`) - Defaults to `false`.
* `disabled` (`:boolean`) - Defaults to `false`.
* `readonly` (`:boolean`) - Defaults to `false`.
* `display` (`:string`) - the length of the dates that the picker writes out (`Intl` `dateStyle`). Defaults to `"medium"`. Must be one of `"short"`, `"medium"`, `"long"`, or `"full"`.
* `on_change` (`:string`) - an event that the picker pushes with `%{"id", "value"}` on each change, for a picker outside a form. Defaults to `nil`.
* `messages` (`:map`) - words that replace the built-in ones, see `Koyomi.Messages`. Defaults to `nil`.
* `class` (`:any`) - classes for the picker element. Defaults to `nil`.
* `seconds` (`:boolean`) - when `true`, the field has seconds. Defaults to `false`.
* `hour_cycle` (`:string`) - the 12 or 24-hour clock; the default is the locale's. Defaults to `nil`. Must be one of `nil`, `"h12"`, or `"h23"`.
* Global attributes are accepted. attributes for the picker element, such as `phx-target`; `aria-describedby` goes to the field. Supports all globals plus: `["form"]`.

# `week_picker`

Renders an ISO week picker: a calendar with week numbers, where a click
picks the whole week. It posts `YYYY-Www`; the `Koyomi.Week` type stores
it as the Monday of the week.

## Attributes

* `field` (`Phoenix.HTML.FormField`) - the form field, for example `@form[:due]`. Defaults to `nil`.
* `id` (`:string`) - the id of the picker element; the default is the field's id with `_picker`. Defaults to `nil`.
* `name` (`:string`) - the input name, without a `field`. Defaults to `nil`.
* `value` (`:any`) - the value, without a `field`. Defaults to `nil`.
* `label_id` (`:string`) - the id of the element that labels the picker (`aria-labelledby`); without it, the picker gets `aria-label` from `label`. Defaults to `nil`.
* `label` (`:string`) - the accessible name when there is no `label_id`; the default is the field name in words. Defaults to `nil`.
* `rules` (`:any`) - the rules of the picker, a `Koyomi.Rules` or its options; give the same to `Koyomi.Changeset`. Defaults to `nil`.
* `min` (`:any`) - a shortcut for the `:min` rule. Defaults to `nil`.
* `max` (`:any`) - a shortcut for the `:max` rule. Defaults to `nil`.
* `locale` (`:string`) - a BCP 47 locale for names, numbers, the order of the fields and the first day of the week; the default is `config :koyomi, locale:`, else "en". Defaults to `nil`.
* `calendar` (`:string`) - the calendar system of the display: the locale's own (`-u-ca-`), else `gregory`; or `japanese`, `buddhist`, `islamic-umalqura`, `hebrew`, `persian`, ... (see the Calendars guide). Defaults to `nil`.
* `time_zone` (`:string`) - the IANA time zone of today and, for a date and time picker, of the wall clock; the default is UTC. Defaults to `nil`.
* `first_day` (`:integer`) - the first day of the week, ISO (1 is Monday, 7 is Sunday); the default is the locale's. Defaults to `nil`.
* `presets` (`:list`) - the presets beside the calendar, see `Koyomi.Presets`. Defaults to `nil`.
* `holidays` (`:any`) - public holidays to mark: a country code ("PT"), a `Koyomi.Holidays.Provider` module, or a list of them. Defaults to `nil`.
* `days` (`:boolean`) - when `true`, the picker asks the LiveView for the content of the days it shows (`koyomi:days`), see the Day content guide. Defaults to `false`.
* `inline` (`:boolean`) - when `true`, the calendar is always shown, with no field and no popover. Defaults to `false`.
* `months` (`:integer`) - the months shown side by side. Defaults to `1`.
* `week_numbers` (`:boolean`) - when `true`, the calendar shows ISO week numbers. Defaults to `false`.
* `outside_days` (`:boolean`) - when `false`, the days of the previous and next months are left blank. Defaults to `true`.
* `typing` (`:boolean`) - when `false`, the popover has no box for typing a date in words. Defaults to `true`.
* `clearable` (`:boolean`) - when `true`, the field has a clear button; the default is `true` unless `required`. Defaults to `nil`.
* `required` (`:boolean`) - Defaults to `false`.
* `disabled` (`:boolean`) - Defaults to `false`.
* `readonly` (`:boolean`) - Defaults to `false`.
* `display` (`:string`) - the length of the dates that the picker writes out (`Intl` `dateStyle`). Defaults to `"medium"`. Must be one of `"short"`, `"medium"`, `"long"`, or `"full"`.
* `on_change` (`:string`) - an event that the picker pushes with `%{"id", "value"}` on each change, for a picker outside a form. Defaults to `nil`.
* `messages` (`:map`) - words that replace the built-in ones, see `Koyomi.Messages`. Defaults to `nil`.
* `class` (`:any`) - classes for the picker element. Defaults to `nil`.
* Global attributes are accepted. attributes for the picker element, such as `phx-target`; `aria-describedby` goes to the field. Supports all globals plus: `["form"]`.

# `year_picker`

Renders a year picker: a field with the year, and a grid of years. It
posts the year as an integer.

## Attributes

* `field` (`Phoenix.HTML.FormField`) - the form field, for example `@form[:due]`. Defaults to `nil`.
* `id` (`:string`) - the id of the picker element; the default is the field's id with `_picker`. Defaults to `nil`.
* `name` (`:string`) - the input name, without a `field`. Defaults to `nil`.
* `value` (`:any`) - the value, without a `field`. Defaults to `nil`.
* `label_id` (`:string`) - the id of the element that labels the picker (`aria-labelledby`); without it, the picker gets `aria-label` from `label`. Defaults to `nil`.
* `label` (`:string`) - the accessible name when there is no `label_id`; the default is the field name in words. Defaults to `nil`.
* `rules` (`:any`) - the rules of the picker, a `Koyomi.Rules` or its options; give the same to `Koyomi.Changeset`. Defaults to `nil`.
* `min` (`:any`) - a shortcut for the `:min` rule. Defaults to `nil`.
* `max` (`:any`) - a shortcut for the `:max` rule. Defaults to `nil`.
* `locale` (`:string`) - a BCP 47 locale for names, numbers, the order of the fields and the first day of the week; the default is `config :koyomi, locale:`, else "en". Defaults to `nil`.
* `calendar` (`:string`) - the calendar system of the display: the locale's own (`-u-ca-`), else `gregory`; or `japanese`, `buddhist`, `islamic-umalqura`, `hebrew`, `persian`, ... (see the Calendars guide). Defaults to `nil`.
* `time_zone` (`:string`) - the IANA time zone of today and, for a date and time picker, of the wall clock; the default is UTC. Defaults to `nil`.
* `first_day` (`:integer`) - the first day of the week, ISO (1 is Monday, 7 is Sunday); the default is the locale's. Defaults to `nil`.
* `presets` (`:list`) - the presets beside the calendar, see `Koyomi.Presets`. Defaults to `nil`.
* `holidays` (`:any`) - public holidays to mark: a country code ("PT"), a `Koyomi.Holidays.Provider` module, or a list of them. Defaults to `nil`.
* `days` (`:boolean`) - when `true`, the picker asks the LiveView for the content of the days it shows (`koyomi:days`), see the Day content guide. Defaults to `false`.
* `inline` (`:boolean`) - when `true`, the calendar is always shown, with no field and no popover. Defaults to `false`.
* `months` (`:integer`) - the months shown side by side. Defaults to `1`.
* `week_numbers` (`:boolean`) - when `true`, the calendar shows ISO week numbers. Defaults to `false`.
* `outside_days` (`:boolean`) - when `false`, the days of the previous and next months are left blank. Defaults to `true`.
* `typing` (`:boolean`) - when `false`, the popover has no box for typing a date in words. Defaults to `true`.
* `clearable` (`:boolean`) - when `true`, the field has a clear button; the default is `true` unless `required`. Defaults to `nil`.
* `required` (`:boolean`) - Defaults to `false`.
* `disabled` (`:boolean`) - Defaults to `false`.
* `readonly` (`:boolean`) - Defaults to `false`.
* `display` (`:string`) - the length of the dates that the picker writes out (`Intl` `dateStyle`). Defaults to `"medium"`. Must be one of `"short"`, `"medium"`, `"long"`, or `"full"`.
* `on_change` (`:string`) - an event that the picker pushes with `%{"id", "value"}` on each change, for a picker outside a form. Defaults to `nil`.
* `messages` (`:map`) - words that replace the built-in ones, see `Koyomi.Messages`. Defaults to `nil`.
* `class` (`:any`) - classes for the picker element. Defaults to `nil`.
* Global attributes are accepted. attributes for the picker element, such as `phx-target`; `aria-describedby` goes to the field. Supports all globals plus: `["form"]`.

---

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