@softize/opus 31.0.0 → 31.1.0

package/CHANGELOG.md

@@ -7,6 +7,13 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 31.1.0 — 2026-10-22
+
+- `DateInput` reúne digitação com máscara brasileira e seleção no calendário. Valores válidos usam datas civis `AAAA-MM-DD`, sem conversão de fuso. `ActionForm` reconhece `widget: 'date'`; entradas incompletas continuam visíveis para validação pelo contrato.
+- `ActionList` e `ActionFilterBar` aceitam `periodControl`, respeitando a posição e a composição dos filtros. Com esse controle, presets do contrato e do estado da lista deixam de sobrescrever o intervalo fornecido pelo consumidor. `CalendarMonthView` oferece uma grade mensal para `ActionList.views`, com agrupamento por data e navegação por teclado; consulta, erro e carregamento permanecem na lista.
+- `Calendar` apresenta mês e ano como `Setembro/2026` por padrão, preservando formatters customizados. A raiz mantém sua identidade entre renderizações para conservar o foco e o primeiro clique de navegação.
+- Dias selecionados e extremidades de intervalos usam o par semântico do botão primário sólido, corrigindo contraste no hover em tema escuro. O comportamento também se aplica aos calendários dos filtros existentes.
+
 ## 31.0.0 — 2026-10-20
 
 - `PageBack` aceita `onBack` e `disabled` para retorno controlado por uma pilha. `href` continua disponível para destinos navegáveis; `PageBackProps` é uma união que impede combinar as duas formas.

package/bin/lib/copy.mjs

@@ -278,6 +278,7 @@ const JSX_PROP_ROLES = new Map([
     ]),
   ],
   ["Input", new Map([["placeholder", "placeholder"]])],
+  ["DateInput", new Map([["placeholder", "placeholder"]])],
   ["InputGroupInput", new Map([["placeholder", "placeholder"]])],
   ["InputGroupTextarea", new Map([["placeholder", "placeholder"]])],
   // A ajuda vive num tooltip (portal): não herda transformação nem classe do label.
@@ -397,6 +398,7 @@ const JSX_PROP_CLASS = new Map([
   ],
   ["CommandInput", new Map([["placeholder", "className"]])],
   ["Input", new Map([["placeholder", "className"]])],
+  ["DateInput", new Map([["placeholder", "className"]])],
   ["InputGroupInput", new Map([["placeholder", "className"]])],
   ["InputGroupTextarea", new Map([["placeholder", "className"]])],
   [
@@ -431,6 +433,7 @@ const JSX_PROP_STYLE = new Map([
   ],
   ["CommandInput", new Map([["placeholder", "style"]])],
   ["Input", new Map([["placeholder", "style"]])],
+  ["DateInput", new Map([["placeholder", "style"]])],
   ["InputGroupInput", new Map([["placeholder", "style"]])],
   ["InputGroupTextarea", new Map([["placeholder", "style"]])],
   [

package/docs/adr/0066-civil-date-input-and-calendar-list.md

@@ -0,0 +1,28 @@
+# ADR 0066 — Datas civis e calendário mensal na lista
+
+- **Status:** aceita para consolidação; publicação é uma etapa separada.
+- **Data:** 2026-10-22.
+
+## Contexto
+
+A gestão de expediente precisa escolher datas sem conversão de fuso e consultar um mês inteiro junto dos filtros de unidade e equipe. O input nativo varia entre navegadores, e uma grade implementada em cada consumidor repetiria navegação e acessibilidade. A experimentação no consumidor Grand Brasil validou a composição antes da consolidação desta API.
+
+## Decisão
+
+`DateInput` compõe Input, Popover e Calendar. Aceita digitação com máscara `DD/MM/AAAA`, colagem ISO e seleção por calendário; datas válidas são emitidas como `AAAA-MM-DD`. Entradas incompletas ou impossíveis permanecem visíveis e são emitidas sem convertê-las numa data válida, para o contrato poder rejeitá-las. O campo recebe foco; o ícone é um adorno. Clique abre o picker sem impedir digitação, Alt+Seta para baixo transfere o foco, e Escape fecha somente o popover. O renderer de `ActionForm` reconhece `widget: 'date'`, preservando controle, reset, validação e acessibilidade do formulário.
+
+`ActionList` e `ActionFilterBar` recebem `periodControl?: ReactNode`. A extensão substitui o seletor padrão no mesmo espaço, respeitando `periodPosition` e a composição com `period.basisFilter`. O consumidor controla o valor temporal e seu estado navegável. Com periodControl, ActionList ignora o preset padrão e os valores period/from/to do estado; somente o input fornecido pelo consumidor define o intervalo. O helper listStateToInput aceita applyPeriod: false para reproduzir esse recorte em detalhes roteados. Sem a propriedade, a API anterior mantém seu comportamento.
+
+`CalendarMonthView<TItem>` é uma visualização, consumida por `ActionList.views`. Recebe mês civil, itens, extração de data, conteúdo, nome acessível e ação por dia. Gera todas as datas do mês e agrupa os itens. A navegação usa setas, Home e End, com uma única parada de Tab. Consulta, filtros, loading, erro e vazio continuam pertencendo à lista. Regras de expediente e feriados ficam no domínio consumidor. A grade é separada do DayPicker por representar uma coleção com conteúdo e ação próprios em cada dia, sem modelo de seleção de datas. Adaptar os botões e o estado de seleção do DayPicker duplicaria essa semântica; a exceção preserva teclado e roles de grid sem copiar a primitiva. A primeira versão usa cabeçalhos em pt-BR e semanas iniciadas no domingo, explicitados na documentação.
+
+O Calendar compartilhado apresenta o mês com inicial maiúscula e barra antes do ano, preservando os formatters customizados. A raiz estável evita perder foco ao renderizar novamente. Dias selecionados usam o par de cores do botão primário sólido, incluindo as extremidades de intervalos.
+
+## Alternativas e consequências
+
+O input nativo foi experimentado e descartado pela inconsistência com os outros campos. Converter datas civis para timestamps criaria dependência de fuso sem necessidade. Copiar a barra de filtros ou inserir um calendário com consulta própria duplicaria responsabilidades já cobertas por ActionList.
+
+As extensões são aditivas. A mudança de legenda e de contraste alcança todos os consumidores do Calendar, portanto inclui regressão do modo de intervalo e dos formatters. Mês inválido em CalendarMonthView é erro de programação; consumidores validam sua entrada antes de renderizar.
+
+## Verificação
+
+Testes de DateInput cobrem máscara, cursor, teclado, datas inválidas, reset e integração com ActionForm. Testes da lista cobrem posicionamento do período e grade com navegação. Testes de Calendar cobrem identidade da raiz, formatter e seleção. Os gates da release incluem tipagem, suíte completa, Chromium e instalação de um consumidor a partir do tarball.

package/docs/adr/README.md

@@ -24,3 +24,5 @@ estar documentado na superfície correspondente, sem exigir a reconstrução des
 - [ADR 0064 — ActionList apresenta itens e conecta fontes externas](0064-action-list-com-itens-e-fontes-externas.md).
 
 - [ADR 0065 — Presentation compõe seções declaradas](0065-presentation-composes-settings-sections.md).
+
+- [ADR 0066 — Datas civis e calendário mensal na lista](0066-civil-date-input-and-calendar-list.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "31.0.0",
+  "version": "31.1.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/src/core/types.ts

@@ -598,6 +598,7 @@ export type OptionsSpec =
 
 /** Overrides declarativos nativos reconhecidos pelo ActionForm. */
 export type BuiltInFieldWidget =
+  | 'date'
   | 'password'
   | 'textarea'
   | 'code'

package/src/ui/components/patterns/form.tsx

@@ -18,7 +18,7 @@
  */
 
 import { createContext, useContext, useEffect, useId } from "react";
-import type { UseFormReturn } from "react-hook-form";
+import { Controller, type UseFormReturn } from "react-hook-form";
 import {
   getLogicalType,
   type FieldWidget,
@@ -38,6 +38,7 @@ import { toast } from "../primitives/sonner.tsx";
 import { Button, type ButtonVariant } from "../primitives/button.tsx";
 import { ButtonGroup } from "../primitives/button-group.tsx";
 import { Input } from "../primitives/input.tsx";
+import { DateInput } from "../primitives/date-input.tsx";
 import { Textarea } from "../primitives/textarea.tsx";
 import { Checkbox } from "../primitives/checkbox.tsx";
 import { IconPicker } from "../primitives/icon-picker.tsx";
@@ -680,6 +681,24 @@ export function ActionFormField({
           aria-describedby={describedBy}
           {...form.register(name)}
         />
+      ) : spec.widget === "date" ? (
+        <Controller
+          name={name}
+          control={form.control}
+          render={({ field }) => (
+            <DateInput
+              id={name}
+              name={field.name}
+              ref={field.ref}
+              value={(field.value as string | undefined) ?? ""}
+              onValueChange={field.onChange}
+              onBlur={field.onBlur}
+              placeholder={spec.placeholder}
+              aria-invalid={errorMessage !== undefined}
+              aria-describedby={describedBy}
+            />
+          )}
+        />
       ) : (
         <Input
           id={name}

package/src/ui/components/patterns/list-calendar.tsx

@@ -0,0 +1,129 @@
+import * as React from "react";
+import { cn } from "../../lib/cn.ts";
+
+export interface CalendarMonthViewProps<TItem> {
+  /** Mês civil no formato YYYY-MM. */
+  month: string;
+  items: readonly TItem[];
+  dateOf: (item: TItem) => string;
+  renderDay: (date: string, items: readonly TItem[]) => React.ReactNode;
+  dayLabel: (date: string, items: readonly TItem[]) => string;
+  onDayClick: (date: string, items: readonly TItem[]) => void;
+  label: string;
+  className?: string;
+}
+
+/** Grade mensal para ActionList.views. Consulta e estados continuam pertencendo à lista. */
+export function CalendarMonthView<TItem>({
+  month,
+  items,
+  dateOf,
+  renderDay,
+  dayLabel,
+  onDayClick,
+  label,
+  className,
+}: CalendarMonthViewProps<TItem>) {
+  const root = React.useRef<HTMLDivElement>(null);
+  const [focused, setFocused] = React.useState(`${month}-01`);
+  if (!/^[1-9]\d{3}-(?:0[1-9]|1[0-2])$/.test(month))
+    throw new RangeError("CalendarMonthView requires YYYY-MM");
+  const first = new Date(`${month}-01T00:00:00Z`);
+  const last = new Date(first);
+  last.setUTCMonth(last.getUTCMonth() + 1, 0);
+  const length = last.getUTCDate();
+  const offset = first.getUTCDay();
+  const rows = Math.ceil((offset + length) / 7);
+  const focusDate = focused.startsWith(`${month}-`) ? focused : `${month}-01`;
+  const grouped = new Map<string, TItem[]>();
+  for (const item of items) {
+    const date = dateOf(item);
+    const group = grouped.get(date) ?? [];
+    group.push(item);
+    grouped.set(date, group);
+  }
+  function move(event: React.KeyboardEvent, day: number) {
+    const weekday = (offset + day - 1) % 7;
+    const delta = {
+      ArrowLeft: -1,
+      ArrowRight: 1,
+      ArrowUp: -7,
+      ArrowDown: 7,
+      Home: -weekday,
+      End: 6 - weekday,
+    }[event.key];
+    if (delta === undefined) return;
+    event.preventDefault();
+    const next = Math.max(1, Math.min(length, day + delta));
+    const date = `${month}-${String(next).padStart(2, "0")}`;
+    setFocused(date);
+    root.current
+      ?.querySelector<HTMLButtonElement>(`[data-calendar-date="${date}"]`)
+      ?.focus();
+  }
+  return (
+    <div className={cn("overflow-x-auto", className)}>
+      <div
+        ref={root}
+        data-slot="calendar-month-view"
+        role="grid"
+        aria-label={label}
+        className="min-w-[35rem] overflow-hidden rounded-lg border"
+      >
+        <div role="row" className="grid grid-cols-7 border-b">
+          {["Dom", "Seg", "Ter", "Qua", "Qui", "Sex", "Sáb"].map((day) => (
+            <div
+              role="columnheader"
+              key={day}
+              className="p-2 text-center text-sm text-muted-foreground"
+            >
+              {day}
+            </div>
+          ))}
+        </div>
+        {Array.from({ length: rows }, (_, row) => (
+          <div
+            role="row"
+            key={row}
+            className="grid grid-cols-7 not-last:border-b"
+          >
+            {Array.from({ length: 7 }, (_, column) => {
+              const day = row * 7 + column - offset + 1;
+              if (day < 1 || day > length)
+                return (
+                  <div
+                    role="gridcell"
+                    key={column}
+                    className="bg-muted/20 not-last:border-r"
+                  />
+                );
+              const date = `${month}-${String(day).padStart(2, "0")}`;
+              const entries = grouped.get(date) ?? [];
+              return (
+                <div
+                  role="gridcell"
+                  key={column}
+                  className="min-w-0 not-last:border-r"
+                >
+                  <button
+                    type="button"
+                    data-calendar-date={date}
+                    tabIndex={date === focusDate ? 0 : -1}
+                    aria-label={dayLabel(date, entries)}
+                    onFocus={() => setFocused(date)}
+                    onKeyDown={(event) => move(event, day)}
+                    onClick={() => onDayClick(date, entries)}
+                    className="flex min-h-28 w-full flex-col gap-2 p-3 text-left text-sm text-foreground hover:bg-muted/40 focus-visible:relative focus-visible:z-10 focus-visible:outline-2 focus-visible:outline-ring focus-visible:-outline-offset-2"
+                  >
+                    <span className="font-medium">{day}</span>
+                    {renderDay(date, entries)}
+                  </button>
+                </div>
+              );
+            })}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/ui/components/patterns/list.tsx

@@ -315,6 +315,8 @@ export interface ActionFilterBarProps {
   refreshing?: boolean;
   /** Posição do período em relação aos filtros inline. Também pode ancorá-lo após um filtro. */
   periodPosition?: "before" | "after" | { afterFilter: string };
+  /** Substitui o seletor de período; estado e input temporal ficam com o consumidor. */
+  periodControl?: ReactNode;
   /** Composição do período com uma dimensão temporal declarada como filtro inline. */
   period?: PeriodLayout;
   /** Controles auxiliares, agrupados com o refresh em um ButtonGroup espaçado. */
@@ -416,6 +418,8 @@ interface ActionListBaseProps<TInput, TItem> {
   advancedFilters?: AdvancedFiltersLayout;
   /** Posição do período em relação aos filtros inline. Também pode ancorá-lo após um filtro. */
   periodPosition?: "before" | "after" | { afterFilter: string };
+  /** Substitui o seletor de período; estado e input temporal ficam com o consumidor. */
+  periodControl?: ReactNode;
   /** Composição do período com uma dimensão temporal declarada como filtro inline. */
   period?: PeriodLayout;
   /** Views alternativas da mesma listagem — o segment na toolbar alterna entre a
@@ -1414,6 +1418,7 @@ export function ActionFilterBar({
   onRefresh,
   refreshing = false,
   periodPosition = "before",
+  periodControl: customPeriodControl,
   period,
   controls,
   actions,
@@ -1433,8 +1438,9 @@ export function ActionFilterBar({
     periods[0]?.value ??
     null;
   const activePeriod = state.period ?? defaultPeriod;
+  const hasPeriod = customPeriodControl != null || periods.length > 0;
   const periodBasisEntry =
-    periods.length > 0 && period !== undefined
+    hasPeriod && period !== undefined
       ? inlineSpecs.find(([name]) => name === period.basisFilter)
       : undefined;
   const [advancedOpen, setAdvancedOpen] = useState(false);
@@ -1484,18 +1490,18 @@ export function ActionFilterBar({
     });
   const inlineControlCount =
     inlineSpecs.filter(([name]) => name !== periodBasisEntry?.[0]).length +
-    (periods.length > 0 ? 1 : 0) +
+    (hasPeriod ? 1 : 0) +
     (hasSearch ? 1 : 0);
   const showInlineLabels = inlineControlCount > 1;
-  const searchAtActionsEnd =
-    hasSearch && (inlineSpecs.length > 0 || periods.length > 0);
+  const searchAtActionsEnd = hasSearch && (inlineSpecs.length > 0 || hasPeriod);
   const periodAfterFilter =
     typeof periodPosition === "object" ? periodPosition.afterFilter : null;
   const anchoredPeriodExists = inlineSpecs.some(
     ([name]) => name === periodAfterFilter,
   );
   const periodField =
-    periods.length > 0 ? (
+    customPeriodControl ??
+    (periods.length > 0 ? (
       <PeriodControl
         periods={periods}
         period={activePeriod}
@@ -1518,7 +1524,7 @@ export function ActionFilterBar({
           })
         }
       />
-    ) : null;
+    ) : null);
   const periodControl =
     periodField === null || periodBasisEntry !== undefined ? null : (
       <Labeled
@@ -1585,24 +1591,26 @@ export function ActionFilterBar({
                       aria-hidden="true"
                     />
                     <div className="pl-2">
-                      <PeriodControl
-                        periods={periods}
-                        period={activePeriod}
-                        from={state.from}
-                        to={state.to}
-                        clearable={false}
-                        embedded
-                        onChange={(next) =>
-                          onStateChange({
-                            ...state,
-                            ...next,
-                            period:
-                              next.period === defaultPeriod
-                                ? null
-                                : next.period,
-                          })
-                        }
-                      />
+                      {customPeriodControl ?? (
+                        <PeriodControl
+                          periods={periods}
+                          period={activePeriod}
+                          from={state.from}
+                          to={state.to}
+                          clearable={false}
+                          embedded
+                          onChange={(next) =>
+                            onStateChange({
+                              ...state,
+                              ...next,
+                              period:
+                                next.period === defaultPeriod
+                                  ? null
+                                  : next.period,
+                            })
+                          }
+                        />
+                      )}
                     </div>
                     <Separator
                       data-slot="action-filter-period-separator"
@@ -1831,6 +1839,7 @@ export function ActionList<TInput, TItem>({
   filterIcons,
   advancedFilters,
   periodPosition,
+  periodControl,
   period,
   views,
   batch,
@@ -1966,6 +1975,7 @@ export function ActionList<TInput, TItem>({
     hasSearch ||
     filterSpecs.length > 0 ||
     periods.length > 0 ||
+    periodControl != null ||
     hasSegment ||
     viewControls != null ||
     (title === undefined && toolbarActions != null) ||
@@ -1977,8 +1987,9 @@ export function ActionList<TInput, TItem>({
         input: input as Record<string, unknown>,
         filterDefaults,
         pageSize,
+        applyPeriod: periodControl == null,
       }) as TInput,
-    [input, state, pageSize, filterDefaults, action],
+    [input, state, pageSize, filterDefaults, action, periodControl],
   );
 
   const inputKey = JSON.stringify([effectiveInput, activeGroupBy]);
@@ -2262,6 +2273,7 @@ export function ActionList<TInput, TItem>({
         filterIcons={filterIcons}
         advancedFilters={advancedFilters}
         periodPosition={periodPosition}
+        periodControl={periodControl}
         period={period}
         controls={
           <>
@@ -3283,10 +3295,13 @@ export function listStateToInput(
     input = {},
     filterDefaults,
     pageSize = 50,
+    applyPeriod = true,
   }: {
     input?: Record<string, unknown>;
     filterDefaults?: Record<string, string>;
     pageSize?: number;
+    /** False quando o consumidor fornece integralmente o intervalo temporal em input. */
+    applyPeriod?: boolean;
   } = {},
 ): Record<string, unknown> {
   const sort = state.sort ?? action.sort?.default?.[0] ?? null;
@@ -3306,11 +3321,12 @@ export function listStateToInput(
   }
   // Período: preset materializa AQUI (a URL guarda o preset relativo); custom usa o
   // range. state.period null = o default do contrato (sempre aplicado).
-  const effectivePeriod =
-    state.period ??
-    action.periods?.find((p) => p.default === true)?.value ??
-    action.periods?.[0]?.value ??
-    null;
+  const effectivePeriod = applyPeriod
+    ? (state.period ??
+      action.periods?.find((p) => p.default === true)?.value ??
+      action.periods?.[0]?.value ??
+      null)
+    : null;
   let range: { from: string; to: string } | null = null;
   if (
     effectivePeriod === "custom" &&

package/src/ui/components/primitives/calendar.tsx

@@ -7,8 +7,10 @@ import {
 import { ptBR } from "date-fns/locale";
 import {
   DayPicker,
+  DateLib,
   getDefaultClassNames,
   type DayButton,
+  type RootProps,
 } from "react-day-picker";
 
 import { cn } from "../../lib/cn.ts";
@@ -16,7 +18,9 @@ import { Button, buttonVariants } from "./button.tsx";
 
 /** Rótulos acessíveis da navegação em pt-BR — o react-day-picker só traduz nomes de mês e
  *  dia pelo `locale`; os aria-labels dos controles continuariam em inglês. */
-const LABELS_PT_BR: NonNullable<React.ComponentProps<typeof DayPicker>["labels"]> = {
+const LABELS_PT_BR: NonNullable<
+  React.ComponentProps<typeof DayPicker>["labels"]
+> = {
   labelPrevious: () => "Mês anterior",
   labelNext: () => "Próximo mês",
   labelMonthDropdown: () => "Escolher o mês",
@@ -34,6 +38,17 @@ const LABELS_PT_BR: NonNullable<React.ComponentProps<typeof DayPicker>["labels"]
   },
 };
 
+function CalendarRoot({ className, rootRef, ...props }: RootProps) {
+  return (
+    <div
+      data-slot="calendar"
+      ref={rootRef}
+      className={cn(className)}
+      {...props}
+    />
+  );
+}
+
 function Calendar({
   className,
   classNames,
@@ -63,17 +78,27 @@ function Calendar({
       )}
       captionLayout={captionLayout}
       formatters={{
+        formatCaption: (date, options, dateLib) => {
+          const caption = (
+            dateLib ??
+            new DateLib({
+              ...options,
+              locale: { ...ptBR, ...locale, ...options?.locale },
+            })
+          ).format(date, "LLLL/yyyy");
+          return (
+            caption.charAt(0).toLocaleUpperCase(locale.code) + caption.slice(1)
+          );
+        },
         // O dateLib já carrega o `locale` em vigor: o dropdown fala a mesma língua da legenda.
         formatMonthDropdown: (date, dateLib) =>
-          dateLib?.format(date, "LLL") ?? date.toLocaleString("pt-BR", { month: "short" }),
+          dateLib?.format(date, "LLL") ??
+          date.toLocaleString("pt-BR", { month: "short" }),
         ...formatters,
       }}
       classNames={{
         root: cn("w-fit", defaultClassNames.root),
-        months: cn(
-          "relative flex flex-row gap-4",
-          defaultClassNames.months,
-        ),
+        months: cn("relative flex flex-row gap-4", defaultClassNames.months),
         month: cn("flex w-full flex-col gap-4", defaultClassNames.month),
         nav: cn(
           "absolute inset-x-0 top-0 flex w-full items-center justify-between gap-1",
@@ -156,16 +181,7 @@ function Calendar({
         ...classNames,
       }}
       components={{
-        Root: ({ className, rootRef, ...props }) => {
-          return (
-            <div
-              data-slot="calendar"
-              ref={rootRef}
-              className={cn(className)}
-              {...props}
-            />
-          );
-        },
+        Root: CalendarRoot,
         Chevron: ({ className, orientation, ...props }) => {
           if (orientation === "left") {
             return (
@@ -219,7 +235,12 @@ function CalendarDayButton({
   return (
     <Button
       ref={ref}
-      variant="ghost"
+      context={
+        modifiers.selected && !modifiers.range_middle ? "primary" : "neutral"
+      }
+      variant={
+        modifiers.selected && !modifiers.range_middle ? "solid" : "ghost"
+      }
       size="icon"
       data-day={day.date.toLocaleDateString()}
       data-selected-single={
@@ -232,7 +253,7 @@ function CalendarDayButton({
       data-range-end={modifiers.range_end}
       data-range-middle={modifiers.range_middle}
       className={cn(
-        "flex aspect-square size-auto w-full min-w-(--cell-size) flex-col gap-1 leading-none font-normal group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-[0.1875rem] group-data-[focused=true]/day:ring-ring/50 data-[range-end=true]:rounded-md data-[range-end=true]:rounded-r-md data-[range-end=true]:bg-primary data-[range-end=true]:text-primary-foreground data-[range-middle=true]:rounded-none data-[range-middle=true]:bg-accent data-[range-middle=true]:text-accent-foreground data-[range-start=true]:rounded-md data-[range-start=true]:rounded-l-md data-[range-start=true]:bg-primary data-[range-start=true]:text-primary-foreground data-[selected-single=true]:bg-primary data-[selected-single=true]:text-primary-foreground dark:hover:text-accent-foreground [&>span]:text-xs [&>span]:opacity-70",
+        "flex aspect-square size-auto w-full min-w-(--cell-size) flex-col gap-1 leading-none font-normal group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-[0.1875rem] group-data-[focused=true]/day:ring-ring/50 data-[range-end=true]:rounded-md data-[range-end=true]:rounded-r-md data-[range-middle=true]:rounded-none data-[range-middle=true]:bg-accent data-[range-middle=true]:text-accent-foreground data-[range-start=true]:rounded-md data-[range-start=true]:rounded-l-md [&>span]:text-xs [&>span]:opacity-70",
         defaultClassNames.day,
         className,
       )}

package/src/ui/components/primitives/date-input.tsx

@@ -0,0 +1,276 @@
+import * as React from "react";
+import { CalendarDays } from "lucide-react";
+import { Input, type InputProps } from "./input.tsx";
+import { Calendar } from "./calendar.tsx";
+import { Popover, PopoverAnchor, PopoverContent } from "./popover.tsx";
+
+export interface DateInputProps extends Omit<
+  InputProps,
+  | "type"
+  | "value"
+  | "defaultValue"
+  | "onChange"
+  | "icon"
+  | "trailing"
+  | "min"
+  | "max"
+  | "step"
+> {
+  /** Data civil ISO; durante a digitação, pode conter texto ainda inválido. */
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+}
+
+function parseDate(value: string): Date | undefined {
+  const parts = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!parts) return undefined;
+  const [, year, month, day] = parts.map(Number);
+  if (year < 1 || month < 1 || month > 12 || day < 1 || day > 31)
+    return undefined;
+  const date = new Date(0);
+  date.setHours(0, 0, 0, 0);
+  date.setFullYear(year, month - 1, day);
+  return date.getFullYear() === year &&
+    date.getMonth() === month - 1 &&
+    date.getDate() === day
+    ? date
+    : undefined;
+}
+
+function serializeDate(date: Date): string {
+  return `${String(date.getFullYear()).padStart(4, "0")}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+}
+
+function valueFromText(text: string): string {
+  if (parseDate(text)) return text;
+  const parts =
+    /^(\d{2})\/(\d{2})\/(\d{4})$/.exec(text) ??
+    /^(\d{2})(\d{2})(\d{4})$/.exec(text);
+  if (!parts) return text;
+  const candidate = `${parts[3]}-${parts[2]}-${parts[1]}`;
+  return parseDate(candidate) ? candidate : text;
+}
+
+function maskDate(text: string): string {
+  const iso = /^(\d{4})-(\d{2})-(\d{2})$/.exec(text);
+  const digits = (
+    iso ? `${iso[3]}${iso[2]}${iso[1]}` : text.replace(/\D/g, "")
+  ).slice(0, 8);
+  return (
+    digits.slice(0, 2) +
+    (digits.length >= 2 ? "/" : "") +
+    digits.slice(2, 4) +
+    (digits.length >= 4 ? "/" : "") +
+    digits.slice(4)
+  );
+}
+
+function positionAfterDigits(count: number): number {
+  return count + (count >= 2 ? 1 : 0) + (count >= 4 ? 1 : 0);
+}
+
+export const DateInput = React.forwardRef<HTMLInputElement, DateInputProps>(
+  function DateInput(
+    {
+      value,
+      defaultValue = "",
+      onValueChange,
+      disabled,
+      readOnly,
+      name,
+      form,
+      placeholder = "DD/MM/AAAA",
+      onKeyDown,
+      ...props
+    },
+    ref,
+  ) {
+    const inputRef = React.useRef<HTMLInputElement>(null);
+    const calendarId = React.useId();
+    const fieldRef = React.useRef<HTMLDivElement>(null);
+    const restoreInputFocus = React.useRef(false);
+    React.useImperativeHandle(ref, () => inputRef.current!);
+    const [internalValue, setInternalValue] = React.useState(defaultValue);
+    const currentValue = value ?? internalValue;
+    const selected = parseDate(currentValue);
+    const text = selected
+      ? currentValue.split("-").reverse().join("/")
+      : currentValue;
+    const [open, setOpen] = React.useState(false);
+    const openRef = React.useRef(open);
+    openRef.current = open;
+    const [focusCalendar, setFocusCalendar] = React.useState(false);
+    const [calendarSession, setCalendarSession] = React.useState(0);
+    const [caret, setCaret] = React.useState<{ position: number }>();
+    const [month, setMonth] = React.useState(() => selected ?? new Date());
+
+    React.useLayoutEffect(() => {
+      const input = inputRef.current;
+      if (caret && input && document.activeElement === input) {
+        input.setSelectionRange(caret.position, caret.position);
+      }
+    }, [caret]);
+
+    React.useEffect(() => {
+      const ownerForm = inputRef.current?.form;
+      if (value !== undefined || !ownerForm) return;
+      const reset = () => setInternalValue(defaultValue);
+      ownerForm.addEventListener("reset", reset);
+      return () => ownerForm.removeEventListener("reset", reset);
+    }, [value, defaultValue, form]);
+
+    const change = (next: string) => {
+      if (value === undefined) setInternalValue(next);
+      onValueChange?.(next);
+    };
+    const changeOpen = (next: boolean) => {
+      if (
+        next &&
+        (disabled || readOnly || inputRef.current?.matches(":disabled"))
+      )
+        return;
+      if (next) {
+        setMonth(selected ?? new Date());
+        if (!open) setCalendarSession((session) => session + 1);
+      }
+      setOpen(next);
+    };
+
+    return (
+      <Popover open={open && !disabled && !readOnly} onOpenChange={changeOpen}>
+        {name && (
+          <input
+            type="hidden"
+            name={name}
+            form={form}
+            value={currentValue}
+            disabled={disabled}
+          />
+        )}
+        <PopoverAnchor asChild>
+          <div
+            ref={fieldRef}
+            onClick={(event) => {
+              if (event.defaultPrevented) return;
+              if (
+                disabled ||
+                readOnly ||
+                inputRef.current?.matches(":disabled")
+              )
+                return;
+              inputRef.current?.focus();
+              setFocusCalendar(false);
+              changeOpen(true);
+            }}
+          >
+            <Input
+              {...props}
+              ref={inputRef}
+              form={form}
+              type="text"
+              inputMode="numeric"
+              value={text}
+              placeholder={placeholder}
+              disabled={disabled}
+              readOnly={readOnly}
+              role="combobox"
+              aria-expanded={open}
+              aria-haspopup="dialog"
+              aria-controls={open ? calendarId : undefined}
+              aria-keyshortcuts="Alt+ArrowDown"
+              onChange={(event) => {
+                const input = event.target;
+                let raw = input.value;
+                let cursor = input.selectionStart ?? raw.length;
+                const inputType = (event.nativeEvent as InputEvent).inputType;
+                // A barra pertence à máscara: apagar junto dela também remove o dígito adjacente,
+                // inclusive em teclados virtuais que não emitem keydown de Backspace ou Delete.
+                if (
+                  raw.length === text.length - 1 &&
+                  raw.replace(/\D/g, "") === text.replace(/\D/g, "")
+                ) {
+                  if (inputType === "deleteContentBackward" && cursor > 0) {
+                    raw = raw.slice(0, cursor - 1) + raw.slice(cursor);
+                    cursor -= 1;
+                  } else if (inputType === "deleteContentForward") {
+                    raw = raw.slice(0, cursor) + raw.slice(cursor + 1);
+                  }
+                }
+                const masked = maskDate(raw);
+                const digitCount = raw
+                  .slice(0, cursor)
+                  .replace(/\D/g, "").length;
+                setCaret({
+                  position: Math.min(
+                    masked.length,
+                    positionAfterDigits(digitCount),
+                  ),
+                });
+                change(valueFromText(masked));
+              }}
+              onKeyDown={(event) => {
+                onKeyDown?.(event);
+                if (event.defaultPrevented) return;
+                if (event.altKey && event.key === "ArrowDown") {
+                  event.preventDefault();
+                  setFocusCalendar(true);
+                  changeOpen(true);
+                }
+              }}
+              trailing={<CalendarDays aria-hidden="true" className="size-4" />}
+            />
+          </div>
+        </PopoverAnchor>
+        <PopoverContent
+          id={calendarId}
+          className="w-auto p-0"
+          align="start"
+          aria-label="Escolher data"
+          onOpenAutoFocus={(event) => {
+            event.preventDefault();
+            if (focusCalendar) {
+              (event.target as HTMLElement)
+                .querySelector<HTMLButtonElement>('[data-day][tabindex="0"]')
+                ?.focus();
+            }
+          }}
+          onInteractOutside={(event) => {
+            if (fieldRef.current?.contains(event.target as Node))
+              event.preventDefault();
+          }}
+          onEscapeKeyDown={() => {
+            restoreInputFocus.current = true;
+          }}
+          onCloseAutoFocus={(event) => {
+            event.preventDefault();
+            // O fechamento anterior pode terminar depois de uma reabertura rápida.
+            if (restoreInputFocus.current && !openRef.current) {
+              inputRef.current?.focus();
+            }
+            restoreInputFocus.current = false;
+          }}
+        >
+          <Calendar
+            // DayPicker aplica autoFocus apenas na montagem, inclusive em reaberturas durante a animação.
+            key={`${calendarSession}-${focusCalendar}`}
+            mode="single"
+            required
+            autoFocus={focusCalendar}
+            startMonth={parseDate("0001-01-01")}
+            endMonth={parseDate("9999-12-01")}
+            month={month}
+            onMonthChange={setMonth}
+            selected={selected}
+            onSelect={(date) => {
+              if (inputRef.current?.matches(":disabled")) return;
+              change(serializeDate(date));
+              restoreInputFocus.current = true;
+              setOpen(false);
+            }}
+          />
+        </PopoverContent>
+      </Popover>
+    );
+  },
+);

package/src/ui/docs/content/action-form.md

@@ -122,7 +122,11 @@ referência; itens estáticos permanecem como declarados no contrato.
 
 ## Widgets declarativos
 
-`FieldSpec.widget` aceita `password`, `textarea`, `code`, `lines`, `refItems`, `icon` e `toggle-group`.
+`FieldSpec.widget` aceita `date`, `password`, `textarea`, `code`, `lines`, `refItems`, `icon` e `toggle-group`.
+Para uma data civil, declare `widget: 'date'` e use uma string `YYYY-MM-DD` no schema e no
+valor inicial. O formulário usa o [`DateInput`](/ui/date-input), com digitação em `DD/MM/AAAA`
+e calendário em pt-BR. O valor válido enviado continua sendo a data civil, sem conversão para UTC.
+Texto incompleto ou inválido chega ao schema para validação; use um schema de data civil.
 `password` usa um input de senha com `autocomplete="new-password"`, adequado a cadastro e redefinição.
 O literal canônico do grupo de escolhas é sempre kebab-case: `widget: 'toggle-group'`. Em enum ele
 renderiza seleção única; em array de enum, seleção múltipla. As opções seguem a mesma precedência e

package/src/ui/docs/content/action-list.md

@@ -568,6 +568,26 @@ render(
 );
 ```
 
+## Período controlado pelo consumidor
+
+Use `periodControl` quando a coleção precisar de uma navegação temporal própria, como um mês de expediente. O controle ocupa o mesmo espaço do seletor padrão e respeita `periodPosition`, inclusive a composição com `period.basisFilter`.
+
+Com uma action que recebe `month`, mantenha o valor no consumidor e envie-o no input:
+
+```tsx
+const [month, setMonth] = useState("2026-11")
+
+<ActionList
+  action={deliveryListContract}
+  input={{ month }}
+  periodControl={<Input type="month" value={month} onChange={(event) => setMonth(event.target.value)} />}
+/>
+```
+
+Quando `periodControl` está presente, ActionList ignora os presets de `action.periods` e os campos `period`, `from` e `to` do estado da lista, inclusive os recuperados da URL. O intervalo vem do `input` do consumidor; não há filtro temporal oculto. Sem o controle personalizado, o comportamento padrão permanece. Ao hidratar detalhes pelo helper `listStateToInput`, passe `applyPeriod: false` para manter o mesmo recorte.
+
+Para distribuir os resultados pelos dias, componha a extensão `views` com [CalendarMonthView](/ui/calendar-month-view). A lista continua responsável pela consulta e pelos estados assíncronos.
+
 ## Propriedades de ActionFilterBar
 
 | Propriedade       | Tipo                                                                                                        | Padrão                                    | Descrição                                                                                       |
@@ -580,6 +600,7 @@ render(
 | `filterIcons`     | `Record<string, ReactNode>`                                                                                 |                                           | Associa um ícone leading ao controle de cada filtro.                                            |
 | `advancedFilters` | `{ columns?: 1 \| 2 \| 3; sectionIcons?: Record<string, ReactNode>; sectionVariant?: 'plain' \| 'framed' }` | `{ columns: 1, sectionVariant: 'plain' }` | Define as colunas, os ícones e o tratamento das seções; o Opus deriva a largura correspondente. |
 | `periodPosition`  | `'before' \| 'after' \| { afterFilter: string }`                                                            | `'before'`                                | Posiciona o período antes, depois ou imediatamente após um filtro inline.                       |
+| `periodControl` | `ReactNode` | — | Controle temporal do consumidor. Substitui o seletor padrão; em ActionList, também desativa a aplicação automática dos presets ao input. |
 | `period`          | `{ basisFilter: string }`                                                                                   |                                           | Reúne o período e o filtro inline indicado em um único controle.                                |
 | `onRefresh`       | `() => Promise<void> \| void`                                                                               |                                           | Exibe a ação de recarregar e executa a consulta do consumidor.                                  |
 | `refreshing`      | `boolean`                                                                                                   | `false`                                   | Desabilita e anima a ação de recarregar durante a consulta.                                     |
@@ -636,6 +657,7 @@ para fora de `toolbarActions`.
 | `filterIcons`           | `Record<string, ReactNode>`                                                                                 |                                                                                                                                       | Ícones leading dos filtros, indexados pelo nome declarado no contrato.                                                                                                                                         |
 | `advancedFilters`       | `{ columns?: 1 \| 2 \| 3; sectionIcons?: Record<string, ReactNode>; sectionVariant?: 'plain' \| 'framed' }` | `{ columns: 1, sectionVariant: 'plain' }`                                                                                             | Define as colunas, os ícones e o tratamento dos grupos; o Opus deriva a largura correspondente do diálogo.                                                                                                     |
 | `periodPosition`        | `'before' \| 'after' \| { afterFilter: string }`                                                            | `'before'`                                                                                                                            | Posiciona o período antes, depois ou imediatamente após um filtro inline.                                                                                                                                      |
+| `periodControl` | `ReactNode` | — | Controle temporal do consumidor. Substitui o seletor padrão; em ActionList, também desativa a aplicação automática dos presets ao input. |
 | `period`                | `{ basisFilter: string }`                                                                                   |                                                                                                                                       | Reúne o período e o filtro inline indicado em um único controle.                                                                                                                                               |
 | `views`                 | `Record<string, ActionListView<TItem>>`                                                                     |                                                                                                                                       | Visualizações alternativas `{ label, icon?, render }`; o seletor alterna entre a tabela e estas.                                                                                                               |
 | `beforeContent`         | `ReactNode \| (input: TInput) => ReactNode`                                                                                                 |                                                                                                                                       | Conteúdo entre a toolbar e o corpo; a função recebe o mesmo input efetivo da consulta, para resumos que acompanham o recorte.                                                                                                                                 |

package/src/ui/docs/content/calendar-month-view.md

@@ -0,0 +1,50 @@
+## Registros distribuídos pelos dias
+
+Use `CalendarMonthView` para consultar uma agenda ou expediente com conteúdo em cada dia. Para escolher uma data num formulário, use [DateInput](/ui/date-input); para selecionar um intervalo, use [Calendar](/ui/calendar).
+
+O exemplo mostra um registro no mês inteiro. Clique ou use o teclado para abrir um dia:
+
+```tsx preview
+const [selected, setSelected] = useState("")
+const entries = [{ date: "2026-11-02", title: "Expediente especial" }]
+
+render(
+  <div className="space-y-3">
+    <CalendarMonthView
+      month="2026-11"
+      label="Agenda de novembro"
+      items={entries}
+      dateOf={(entry) => entry.date}
+      renderDay={(_date, items) => items.map((entry) => <span key={entry.title}>{entry.title}</span>)}
+      dayLabel={(date, items) => `${date}: ${items.map((entry) => entry.title).join(", ") || "Sem registros"}`}
+      onDayClick={(date) => setSelected(date)}
+    />
+    {selected && <p>Data selecionada: {selected}</p>}
+  </div>,
+)
+```
+
+A grade sempre mostra todos os dias do mês, mesmo sem itens. Ela agrupa os registros por `dateOf`, sem consultar dados ou calcular regras de expediente. Datas são strings civis; o componente não aplica o fuso do navegador.
+
+## Dentro de ActionList
+
+Forneça a grade no renderer de `views`. A [ActionList](/ui/action-list) mantém consulta, filtros, carregamento, erro e vazio; use `paginate: false` no contrato para que uma página de resultados não esconda dias com registros. `periodControl` permite navegar pelo mês no espaço de período da lista, com o valor temporal controlado pelo consumidor.
+
+## Teclado e limites
+
+Tab entra em um único dia. Setas esquerda e direita percorrem dias; cima e baixo avançam uma semana. Home e End levam ao início ou fim da semana visível. Enter e Espaço acionam o dia focado. A navegação fica dentro do mês: o consumidor fornece os controles para trocar de mês.
+
+A semana começa no domingo, com cabeçalhos em pt-BR. Mês inválido é erro de programação; valide valores da URL antes de renderizar. O padrão não marca hoje automaticamente nem implementa seleção de datas ou PageUp/PageDown. A raiz da grade expõe `data-slot="calendar-month-view"`.
+
+## Propriedades de CalendarMonthView
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `month` | `string` | Obrigatória | Mês civil `AAAA-MM`, de 1000-01 a 9999-12. |
+| `items` | `readonly TItem[]` | Obrigatória | Registros do mês, fornecidos pela coleção. |
+| `dateOf` | `(item: TItem) => string` | Obrigatória | Data civil `AAAA-MM-DD` de cada registro. |
+| `renderDay` | `(date: string, items: readonly TItem[]) => ReactNode` | Obrigatória | Conteúdo do dia; evite controles interativos dentro do botão. |
+| `dayLabel` | `(date: string, items: readonly TItem[]) => string` | Obrigatória | Nome acessível do botão, incluindo data e contexto útil. |
+| `onDayClick` | `(date: string, items: readonly TItem[]) => void` | Obrigatória | Abre ou executa a ação do dia. |
+| `label` | `string` | Obrigatória | Nome acessível da grade. |
+| `className` | `string` | — | Classes do contêiner externo, que permite rolagem horizontal em telas estreitas. |

package/src/ui/docs/content/calendar.md

@@ -1,7 +1,8 @@
 ## Dia único
 
 Use `Calendar` quando a pessoa precisar escolher datas vendo o mês inteiro, como a data de uma
-entrega ou a janela de um relatório. Para abrir o calendário a partir de um campo, ancore-o em um
+entrega ou a janela de um relatório. Para preencher uma data com digitação e calendário em um
+campo, use [`DateInput`](/ui/date-input). Composições próprias podem ancorá-lo em um
 [`Popover`](/ui/popover).
 
 Com `mode="single"`, a seleção é uma `Date`, controlada por `selected` e `onSelect`. `defaultMonth`
@@ -23,6 +24,8 @@ render(
 O calendário usa pt-BR por padrão: os nomes de mês e de dia vêm do `locale` (`ptBR`, de
 `date-fns/locale`) e os controles de navegação têm nomes acessíveis em português. Passe outro
 `locale` para trocar o idioma; `labels` substitui nomes acessíveis individualmente.
+O título usa mês com inicial maiúscula e barra antes do ano, como `Setembro/2026`.
+Esse formato também aparece nos campos `DateInput`; `formatters.formatCaption` permite substituí-lo.
 
 ## Intervalo
 
@@ -181,3 +184,5 @@ no nome acessível do dia por `labels.labelDayButton`.
 | `className` | `string` | | Classes somadas ao botão do dia. |
 
 `CalendarDayButton` aceita também as props nativas de `<button>`, repassadas pelo `Calendar`.
+
+Para consultar registros por dia, use [CalendarMonthView](/ui/calendar-month-view). A grade recebe um mês civil válido no formato `AAAA-MM`. Os cabeçalhos estão em pt-BR, e a semana começa no domingo. A consulta e os estados de carregamento e erro pertencem à ActionList.

package/src/ui/docs/content/date-input.md

@@ -0,0 +1,67 @@
+## Digitar ou escolher uma data
+
+Use `DateInput` para preencher uma data civil, como uma entrega ou um feriado. O campo
+exibe `DD/MM/AAAA` e abre o calendário em português ao clicar em qualquer parte do controle.
+O clique mantém o foco na digitação. O ícone é decorativo e não adiciona uma parada de Tab;
+o atalho `Alt` + seta para baixo leva o foco para o calendário.
+
+```tsx preview col md
+function Demo() {
+  const [date, setDate] = useState("2026-11-02")
+  return (
+    <div className="grid gap-2">
+      <Label htmlFor="delivery-date">Data de entrega</Label>
+      <DateInput id="delivery-date" value={date} onValueChange={setDate} />
+    </div>
+  )
+}
+render(<Demo />)
+```
+
+A máscara insere as barras durante a digitação: basta informar `02112026`. Também é possível
+digitar `02/11/2026`, colar `2026-11-02` ou escolher o dia no
+calendário. Uma data válida é emitida como `2026-11-02`; apagar o campo emite `''`. O componente
+mantém o dia civil, sem transformá-lo em um instante UTC.
+
+Texto incompleto ou uma data impossível permanecem no campo com a máscara, sem conversão para ISO.
+Valide o valor antes de persistir: o componente não troca `31/02/2026` por um dia de março nem
+preserva silenciosamente a data anterior. No `ActionForm`, o schema do contrato mantém essa
+responsabilidade.
+
+## Formulário declarativo
+
+Declare `widget: 'date'` no campo do contrato e use um schema de data civil. O
+[`ActionForm`](/ui/action-form) compõe o `DateInput` com rótulo, hint, erro e foco de validação.
+
+```tsx
+const fields = { date: { label: "Data", widget: "date" as const } }
+const input = z.object({ date: z.string().date("Informe uma data válida.") })
+```
+
+## Teclado e estados
+
+Com foco no campo, `Alt` + seta para baixo abre o calendário e leva o foco até ele. As setas navegam pelos dias;
+selecionar uma data fecha o calendário e devolve o foco ao campo. `Escape` fecha o calendário
+sem fechar o diálogo que o contém. É possível substituir trechos selecionados e apagar com
+`Backspace` ou `Delete`, sem ficar preso às barras da máscara. `disabled` e `readOnly` impedem
+a abertura pelo campo e pelo atalho.
+Associe `Label.htmlFor` ao `id` e use `aria-describedby` para ajuda ou erro.
+
+Para manter um mês inteiro visível, use [`Calendar`](/ui/calendar). Para um campo com estado
+interno, forneça `defaultValue`; `value` e `onValueChange` tornam o componente controlado.
+
+## Propriedades de DateInput
+
+| Propriedade | Tipo | Padrão | Efeito |
+| --- | --- | --- | --- |
+| `value` | `string` | — | Valor controlado: ISO quando válido, texto durante digitação inválida ou incompleta. |
+| `defaultValue` | `string` | `''` | Valor inicial no modo não controlado; restaurado no reset do formulário nativo. |
+| `onValueChange` | `(value: string) => void` | — | Recebe a data civil, o texto em edição ou `''`. |
+| `name` | `string` | — | Envia o valor por um campo oculto no formulário nativo, sem converter para a apresentação brasileira. |
+| `placeholder` | `string` | `DD/MM/AAAA` | Exemplo de formato no campo vazio. |
+| `disabled`, `readOnly` | `boolean` | `false` | Impedem edição e abertura do calendário. |
+| `id`, `ref`, `form`, `onBlur`, `aria-*` | Atributos do input | — | Identificação, foco, vínculo com formulário e descrição acessível do campo visível. |
+| `className` | `string` | — | Classes da moldura do campo, seguindo o Input com adorno. |
+
+O componente não aceita `type`, `onChange`, `icon`, `trailing`, `min`, `max` ou `step`.
+O contrato define os limites de negócio; `onValueChange` substitui o evento de alteração nativo.

package/src/ui/docs/content/input.md

@@ -70,6 +70,9 @@ Associe `htmlFor` no `Label` ao `id` do campo para que o clique no rótulo mova
 `type` é repassado ao `<input>` nativo, permitindo que o navegador escolha teclado e validação
 adequados.
 
+Para datas com digitação em formato brasileiro e calendário do Opus, use
+[`DateInput`](/ui/date-input).
+
 ```tsx preview col md
 <Input type="email" placeholder="Ex.: joao@softize.com.br" />
 <Input type="password" placeholder="Token de serviço" />

package/src/ui/docs/registry.tsx

@@ -67,6 +67,8 @@ import dockMd from "./content/dock.md?raw";
 import breadcrumbMd from "./content/breadcrumb.md?raw";
 import buttonMd from "./content/button.md?raw";
 import calendarMd from "./content/calendar.md?raw";
+import dateInputMd from "./content/date-input.md?raw";
+import calendarMonthViewMd from "./content/calendar-month-view.md?raw";
 import metricCardMd from "./content/metric-card.md?raw";
 import carouselMd from "./content/carousel.md?raw";
 import askMd from "./content/ask.md?raw";
@@ -152,9 +154,15 @@ export const iconScope: Record<string, unknown> = Object.fromEntries(
 );
 
 /** Página conceitual (Começar/Framework/Design/Intro): markdown direto (o H1/lead moram no md). */
-const doc = (content: string, codeCollapsible = true) => (): React.ReactElement => (
-  <DocMarkdown content={content} scope={iconScope} codeCollapsible={codeCollapsible} />
-);
+const doc =
+  (content: string, codeCollapsible = true) =>
+  (): React.ReactElement => (
+    <DocMarkdown
+      content={content}
+      scope={iconScope}
+      codeCollapsible={codeCollapsible}
+    />
+  );
 
 /**
  * Página de componente: o cabeçalho (título + badge de origem + whenToUse) vem do `meta` central
@@ -305,7 +313,11 @@ export const PROTOCOL_SECTIONS: DocSection[] = [
             searchText: mcpMd,
             render: doc(mcpMd),
           },
-          { slug: "ui", title: "Interface com Opus ↗", render: () => <UiRedirect /> },
+          {
+            slug: "ui",
+            title: "Interface com Opus ↗",
+            render: () => <UiRedirect />,
+          },
           {
             slug: "documentation-portal",
             title: "Publicação de documentação",
@@ -585,6 +597,11 @@ export const UI_SECTIONS: DocSection[] = [
               actionFormDialogMd,
             ),
           },
+          {
+            slug: "calendar-month-view",
+            title: "CalendarMonthView",
+            render: comp("CalendarMonthView", "calendar-month-view", calendarMonthViewMd),
+          },
           {
             slug: "action-list",
             title: "Action List",
@@ -637,6 +654,11 @@ export const UI_SECTIONS: DocSection[] = [
             title: "Calendar",
             render: comp("Calendar", "calendar", calendarMd),
           },
+          {
+            slug: "date-input",
+            title: "DateInput",
+            render: comp("DateInput", "date-input", dateInputMd),
+          },
           {
             slug: "checkbox",
             title: "Checkbox",
@@ -890,8 +912,9 @@ export const DOC_SECTIONS: DocSection[] = [
       {
         pages: [
           ...["getting-started", "cycle", "upgrading"].map((slug) =>
-            PROTOCOL_SECTIONS.flatMap((section) => section.groups.flatMap((group) => group.pages))
-              .find((page) => page.slug === slug)!,
+            PROTOCOL_SECTIONS.flatMap((section) =>
+              section.groups.flatMap((group) => group.pages),
+            ).find((page) => page.slug === slug)!,
           ),
           {
             slug: "changelog",
@@ -902,7 +925,9 @@ export const DOC_SECTIONS: DocSection[] = [
       },
       {
         label: "Introdução ao SDK",
-        pages: PROTOCOL_SECTIONS[0]!.groups[0]!.pages.filter((page) => page.slug !== "getting-started"),
+        pages: PROTOCOL_SECTIONS[0]!.groups[0]!.pages.filter(
+          (page) => page.slug !== "getting-started",
+        ),
       },
     ],
   },
@@ -913,8 +938,12 @@ export const DOC_SECTIONS: DocSection[] = [
     label: s.label === "Testes e evolução" ? "Testes" : s.label,
     groups: s.groups.map((g) => ({
       ...g,
-      pages: g.pages.filter((p) => !["ui", "cycle", "upgrading"].includes(p.slug)),
+      pages: g.pages.filter(
+        (p) => !["ui", "cycle", "upgrading"].includes(p.slug),
+      ),
     })),
   })),
-  ...UI_SECTIONS.map((section, index) => index === 0 ? { ...section, label: "Introdução à UI" } : section),
+  ...UI_SECTIONS.map((section, index) =>
+    index === 0 ? { ...section, label: "Introdução à UI" } : section,
+  ),
 ];

package/src/ui/meta.ts

@@ -131,6 +131,12 @@ export const componentMeta = {
     whenToUse:
       "Receba texto em uma única linha com os atributos nativos de `input`. Use `icon` para identidade e `trailing` para uma ação no fim do campo; associe uma Label. Quando precisar combinar múltiplos adornos ou controles na mesma moldura, use InputGroup.",
   },
+  "date-input": {
+    name: "date-input",
+    ancestry: "opus",
+    whenToUse:
+      "Receba uma data por digitação em DD/MM/AAAA ou escolha no calendário. O valor válido permanece uma string civil AAAA-MM-DD, sem conversão de fuso horário. Associe uma Label; no ActionForm, declare widget: 'date'.",
+  },
   label: {
     name: "label",
     ancestry: "shadcn",
@@ -239,11 +245,16 @@ export const componentMeta = {
     whenToUse:
       "Mostre onde a pessoa está quando a página fica vários níveis abaixo da entrada da seção e permita voltar a um nível intermediário. Use BreadcrumbLink nos níveis navegáveis, BreadcrumbPage no nível atual, que não é clicável, BreadcrumbSeparator entre eles e BreadcrumbEllipsis para colapsar trilhas longas. Quando basta voltar ao nível imediatamente acima, use PageBack; para alternar painéis no mesmo nível, Tabs.",
   },
+  "calendar-month-view": {
+    name: "calendar-month-view",
+    ancestry: "opus",
+    whenToUse: "Consulte registros distribuídos pelos dias de um mês, como expediente e agenda. Use como visualização de ActionList para preservar consulta, filtros e estados da coleção.",
+  },
   calendar: {
     name: "calendar",
     ancestry: "shadcn",
     whenToUse:
-      'Permita escolher datas vendo o mês inteiro, como a data de uma entrega ou o período de um relatório. `mode` define a seleção — `single`, `multiple` ou `range` — e o formato de `selected` e `onSelect` (Date, Date[] ou { from, to }). `captionLayout="dropdown"` troca o título do mês por seletores de mês e ano, útil para chegar a um período distante; `numberOfMonths` mostra meses lado a lado e `disabled` impede a escolha de datas específicas. Os textos usam pt-BR por padrão. Para abrir o calendário a partir de um campo, ancore-o em um Popover.',
+      'Permita escolher datas vendo o mês inteiro, como a data de uma entrega ou o período de um relatório. `mode` define a seleção — `single`, `multiple` ou `range` — e o formato de `selected` e `onSelect` (Date, Date[] ou { from, to }). `captionLayout="dropdown"` troca o título do mês por seletores de mês e ano, útil para chegar a um período distante; `numberOfMonths` mostra meses lado a lado e `disabled` impede a escolha de datas específicas. Os textos usam pt-BR por padrão. Para preencher uma data em um campo com digitação e calendário, use DateInput. Use Popover para composições próprias.',
   },
   carousel: {
     name: "carousel",

package/src/ui/react.tsx

@@ -54,6 +54,10 @@ export type {
 } from "./components/primitives/control.ts";
 
 export { Input } from "./components/primitives/input.tsx";
+export {
+  DateInput,
+  type DateInputProps,
+} from "./components/primitives/date-input.tsx";
 
 export { Chat } from "./components/primitives/chat.tsx";
 export type {
@@ -652,3 +656,6 @@ export type {
   PresentationListContentAdapter,
   PresentationRowContentAdapter,
 } from "./components/patterns/presentation-sections.tsx";
+
+export { CalendarMonthView } from "./components/patterns/list-calendar.tsx";
+export type { CalendarMonthViewProps } from "./components/patterns/list-calendar.tsx";