Calendar

Uma grade de mês montada no navegador, com navegação, seleção de uma data ou de um intervalo e suporte a teclado.

Instalação

O Shadwire segue o modelo open code do shadcn/ui: o código-fonte do componente é copiado para o seu app e passa a ser seu. Instale com a CLI:

shadwire add calendar --yes

O item calendar do registry instala estes arquivos:

app/components/ui_component.rb
app/components/ui/calendar_component.rb
app/helpers/ui/calendar_helper.rb
app/javascript/controllers/ui_calendar_controller.js
vendor/shadwire/shadwire.css

Este componente usa Stimulus, então a aplicação precisa de importmap-rails e stimulus-rails com carregamento automático de controllers.

Ainda não instalou a CLI? gem install shadwire e depois shadwire init.

Uso

O servidor renderiza só a estrutura; o controller ui-calendar monta os dias no navegador, então trocar de mês não faz nenhuma requisição. A data escolhida vai para um input[type=hidden], e por isso o calendário funciona dentro de um form_with como qualquer outro campo. Para um campo que abre o calendário em um popover, veja Date Picker.

<%= ui_calendar(selected: Date.current, name: "date", class: "border") %>

<%# Range: two dates, two inputs, two months. %>
<%= ui_calendar(
      mode: :range,
      selected: Date.current..(Date.current + 7),
      number_of_months: 2,
      name: "trip[starts_on]",

<%= ui_calendar(selected: Date.current, name: "date", class: "border") %>

<%# Range: two dates, two inputs, two months. %>
<%= ui_calendar(
      mode: :range,
      selected: Date.current..(Date.current + 7),
      number_of_months: 2,
      name: "trip[starts_on]",
      end_name: "trip[ends_on]"
    ) %>

Exemplos

Padrão

O mês atual, com o dia de hoje selecionado. As setas percorrem os dias, Home/End vão às pontas da semana e PageUp/PageDown trocam de mês.

<%# Inline, the calendar draws its own frame; inside a popover the popover
    plays that part, so the border is left to whoever uses it. %>
<%= ui_calendar(selected: Date.today, name: "date", class: "border") %>

Intervalo

mode: :range guarda duas datas; depois do primeiro clique, passar o mouse mostra o intervalo. number_of_months: 2 mostra dois meses lado a lado.

<%= ui_calendar(
      mode: :range,
      selected: Date.current..(Date.current + 12),
      number_of_months: 2,
      name: "trip[starts_on]",
      end_name: "trip[ends_on]",
      class: "border"
    ) %>

Legenda com selects

caption_layout: :dropdown troca o nome do mês por selects de mês e ano, o que facilita chegar a um ano distante.

<%# `min:`/`max:` disable the days outside the range and bound the year select. %>
<%= ui_calendar(
      caption_layout: :dropdown,
      name: "born_on",
      min: Date.new(1930, 1, 1),
      max: Date.current,
      class: "border"
    ) %>

Referência da API

As datas podem ser um Date ou uma string YYYY-MM-DD. Como todo componente, aceita também class / class_name e **attrs.

Argumento	Padrão	Descrição
`mode`	`:single`	`:range` seleciona um intervalo; o segundo clique define o fim.
`selected`	—	A data escolhida. Em `:range` aceita um intervalo (`Date..Date`).
`from`, `to`	—	O início e o fim do intervalo, se você preferir passá-los separados.
`name`, `end_name`	—	Os inputs escondidos. `name` é a data (ou o início); `end_name`, o fim.
`month`	seleção, senão hoje	Primeiro mês visível.
`min`, `max`	—	Desabilitam os dias fora desse período e limitam os anos do select.
`number_of_months`	`1`	Meses consecutivos lado a lado. `2` é o par usual para intervalos.
`caption_layout`	`:label`	`:dropdown` troca o nome do mês por selects de mês e ano (só com um mês).
`year_range`	−100…+10 anos	Os anos do select. Se `min:`/`max:` forem passados, eles valem.
`dir`	—	`:rtl` espelha a grade, as setas de navegação e as teclas ←/→.
`week_start`	`0`	Primeiro dia da semana: `0` domingo, `1` segunda.
`month_names`, `day_names`	Do I18n	Rótulos da legenda e do cabeçalho. Por padrão, o `date.month_names` e o `date.abbr_day_names` do Rails, no idioma do app; passe arrays para sobrescrevê-los.

Eventos: ui-calendar:change a cada escolha e ui-calendar:connect quando o calendário monta, ambos com detail: { date, from, to }. No sentido contrário, ui-calendar#setDate leva o calendário até uma data vinda de fora.