@varialkit/datepicker 0.1.1

package/docs.md

@@ -0,0 +1,61 @@
+# DatePicker
+
+The DatePicker exposes a calendar panel (`DatePickerPanel`) plus a trigger-driven wrapper (`DatePicker`) that opens the
+panel inside a `Menu` surface. This keeps the calendar usable inline or in a dropdown without duplicating logic.
+
+## Exports
+
+- `DatePicker`
+- `DatePickerPanel`
+
+## Notes
+
+- `DatePicker` uses `MenuDropdown` and disables the menu's automatic close-on-select behavior so month navigation
+  doesn't close the panel.
+- Use `DatePickerPanel` when you need an inline calendar (e.g. inside a card or form section).
+- The default trigger label can be customized via `placeholder` or `formatLabel`.
+- `DatePicker` and `DatePickerPanel` forward `react-day-picker` props like `mode`, `selected`, and `onSelect`.
+
+## Header + View Modes (New)
+
+The calendar header is now custom and always visible at the top of the month view:
+
+- Left nav button: previous month
+- Center buttons: month and year (toggle mode)
+- Right nav button: next month
+
+Clicking the month or year button does **not** open a detached popover. Instead, it swaps the calendar **body** area:
+
+- Default body: day grid
+- Month mode: month grid (Jan-Dec)
+- Year mode: paged year grid (12 years per page)
+
+Selecting a month/year updates the visible calendar month and returns to the default day grid.
+
+## Structure: Where The Logic Lives
+
+- Header controls and mode toggles: `DatePickerMonthCaption` in `src/DatePicker.tsx`
+- Body swapping (day grid vs month/year grids): custom `MonthGrid` component in `DatePickerPanel` (`src/DatePicker.tsx`)
+- Month/year selection content: `DatePickerHeaderPanelView` in `src/DatePicker.tsx`
+- Shared mode state (`activePanel`, `yearPageStart`): `DatePickerHeaderViewContext` in `src/DatePicker.tsx`
+- Layout and active-state styles: `src/DatePicker.scss`
+
+## Props and Behavior Notes
+
+- `DatePickerPanel` defaults:
+  - `captionLayout="label"`
+  - `navLayout="around"`
+  - `hideNavigation=true` (built-in DayPicker nav is hidden because custom header nav is used)
+- `mode`, `selected`, and `onSelect` are mode-aware and support single/multiple/range usage.
+- In dropdown usage (`DatePicker` wrapper), `closeOnSelect` logic remains selection-aware:
+  - single: closes after a valid selection
+  - range: closes after a complete non-single-day range
+  - multiple: remains open by default
+
+## Maintenance Tips
+
+- If header row alignment regresses, check `solara-datepicker__caption-controls` and
+  `solara-datepicker__header-nav-button` in `src/DatePicker.scss`.
+- If month/year view swapping regresses, check the `MonthGrid` override and `activePanel` flow in `src/DatePicker.tsx`.
+- If React warns about unknown DOM props, ensure custom DayPicker component props (e.g. `displayIndex`,
+  `calendarMonth`) are stripped before spreading to native elements.

package/examples.tsx

@@ -0,0 +1,93 @@
+import React, { useState } from "react";
+import type { DateRange } from "react-day-picker";
+import { DatePicker, DatePickerPanel } from "./src";
+
+export const stories = {
+  triggered: {
+    title: "Triggered picker",
+    description: "A menu-triggered date picker with a default button trigger.",
+    showProps: false,
+    render: () => <TriggeredExample />,
+    code: `import React from "react";
+import { DatePicker } from "@solara/datepicker";
+
+export function Example() {
+  const [selected, setSelected] = React.useState<Date | undefined>(new Date());
+
+  return (
+    <DatePicker
+      selected={selected}
+      onSelect={setSelected}
+      placeholder="Pick a date"
+    />
+  );
+}
+`,
+  },
+  range: {
+    title: "Range selection",
+    description: "Use range mode with a two-date selection.",
+    showProps: false,
+    render: () => <RangeExample />,
+    code: `import React from "react";
+import type { DateRange } from "react-day-picker";
+import { DatePicker } from "@solara/datepicker";
+
+export function Example() {
+  const [range, setRange] = React.useState<DateRange | undefined>();
+
+  return (
+    <DatePicker
+      mode="range"
+      selected={range}
+      onSelect={setRange}
+      placeholder="Select range"
+    />
+  );
+}
+`,
+  },
+  inline: {
+    title: "Inline panel",
+    description: "DatePickerPanel can render inline without a menu trigger.",
+    showProps: false,
+    render: () => <InlineExample />,
+    code: `import React from "react";
+import { DatePickerPanel } from "@solara/datepicker";
+
+export function Example() {
+  const [selected, setSelected] = React.useState<Date | undefined>(new Date());
+
+  return (
+    <DatePickerPanel
+      selected={selected}
+      onSelect={setSelected}
+      variant="standalone"
+    />
+  );
+}
+`,
+  },
+};
+
+function TriggeredExample() {
+  const [selected, setSelected] = useState<Date | undefined>(new Date());
+  return <DatePicker selected={selected} onSelect={setSelected} placeholder="Pick a date" />;
+}
+
+function RangeExample() {
+  const [range, setRange] = useState<DateRange | undefined>();
+  return (
+    <DatePicker
+      mode="range"
+      selected={range}
+      onSelect={setRange}
+      placeholder="Select range"
+    />
+  );
+}
+
+function InlineExample() {
+  const [selected, setSelected] = useState<Date | undefined>(new Date());
+  return <DatePickerPanel selected={selected} onSelect={setSelected} variant="standalone" />;
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@varialkit/datepicker",
+  "version": "0.1.1",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./examples": "./examples.tsx"
+  },
+  "files": [
+    "src",
+    "docs.md",
+    "examples.tsx"
+  ],
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "dependencies": {
+    "react-day-picker": "^9.6.3",
+    "@varialkit/menu": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/react": "19.0.10",
+    "react": "19.0.0"
+  }
+}

package/src/DatePicker.scss

@@ -0,0 +1,414 @@
+.solara-datepicker {
+  --datepicker-cell-size: 2.25rem;
+  --datepicker-body-min-height: calc(var(--datepicker-cell-size) * 7);
+  --datepicker-surface: transparent;
+  --datepicker-border: var(--color-divider-primary);
+  --datepicker-text: var(--color-text-primary);
+  --datepicker-text-muted: var(--color-text-secondary);
+  --datepicker-accent: var(--color-accent-primary);
+  --datepicker-accent-muted: color-mix(in srgb, var(--color-accent-primary) 15%, transparent);
+  --datepicker-radius: var(--radius-2);
+  --datepicker-padding: calc(var(--space-2) * var(--spacing-multiplier));
+
+  padding: var(--datepicker-padding);
+  background: var(--datepicker-surface);
+  border-radius: var(--datepicker-radius);
+  border: 1px solid transparent;
+  color: var(--datepicker-text);
+  font-family: var(--font-body);
+}
+
+.solara-datepicker[data-variant="standalone"] {
+  --datepicker-padding: calc(var(--space-3) * var(--spacing-multiplier));
+  --datepicker-surface: var(--color-surface-100);
+  border-color: var(--color-surface-400);
+  box-shadow: var(--elevation-2);
+}
+
+.solara-datepicker__months {
+  display: flex;
+  flex-direction: column;
+  gap: calc(var(--space-3) * var(--spacing-multiplier));
+}
+
+.solara-datepicker__month {
+  display: grid;
+  grid-template-columns: 1fr;
+  grid-template-rows: var(--datepicker-cell-size) auto;
+  row-gap: calc(var(--space-3) * var(--spacing-multiplier));
+}
+
+.solara-datepicker__nav {
+  display: none;
+}
+
+.solara-datepicker__nav-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--datepicker-cell-size);
+  height: var(--datepicker-cell-size);
+  border-radius: var(--radius-2);
+  border: 1px solid var(--color-surface-400);
+  background: var(--color-surface-100);
+  color: var(--color-text-secondary);
+  transition: background-color 0.2s ease, transform 0.2s ease, box-shadow 0.2s ease;
+  pointer-events: auto;
+
+  &:hover {
+    background: var(--color-surface-200);
+  }
+
+  &:active {
+    transform: translateY(1px);
+  }
+
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+}
+
+.solara-datepicker__caption {
+  grid-row: 1;
+  grid-column: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: var(--datepicker-cell-size);
+  padding: 0 calc(var(--datepicker-cell-size) + 0.375rem);
+  z-index: 1;
+}
+
+.solara-datepicker__caption-controls {
+  display: grid;
+  grid-template-columns: var(--datepicker-cell-size) minmax(0, 1fr) var(--datepicker-cell-size);
+  align-items: center;
+  width: 100%;
+  gap: calc(var(--space-1) * var(--spacing-multiplier));
+}
+
+.solara-datepicker__caption-title-buttons {
+  display: inline-flex;
+  align-items: center;
+  justify-self: center;
+  gap: calc(var(--space-1) * var(--spacing-multiplier));
+}
+
+.solara-datepicker__header-nav-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--datepicker-cell-size);
+  height: var(--datepicker-cell-size);
+  border-radius: var(--radius-2);
+  border: 1px solid var(--color-surface-400);
+  background: var(--color-surface-100);
+  color: var(--color-text-secondary);
+  cursor: pointer;
+
+  &:hover {
+    background: var(--color-surface-200);
+  }
+
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+}
+
+.solara-datepicker__caption-controls > .solara-datepicker__header-nav-button:first-child {
+  justify-self: start;
+}
+
+.solara-datepicker__caption-controls > .solara-datepicker__header-nav-button:last-child {
+  justify-self: end;
+}
+
+.solara-datepicker__caption-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: auto;
+  min-height: calc(var(--datepicker-cell-size) - 0.5rem);
+  padding: 0 calc(var(--space-2) * var(--spacing-multiplier));
+  border: none;
+  border-radius: var(--radius-2);
+  background: transparent;
+  color: var(--color-text-primary);
+  font-size: var(--font-size-caption-scaled);
+  font-weight: 500;
+  line-height: 1;
+  white-space: nowrap;
+  cursor: pointer;
+  transition: background-color 0.2s ease, border-color 0.2s ease;
+
+  &:hover {
+    background: var(--color-surface-200);
+  }
+}
+
+.solara-datepicker__caption-button--active {
+  background: var(--datepicker-accent-muted);
+}
+
+.solara-datepicker__caption-panel {
+  position: relative;
+  grid-row: 2;
+  grid-column: 1;
+  min-width: 100%;
+  min-height: var(--datepicker-body-min-height);
+  padding: calc(var(--space-2) * var(--spacing-multiplier));
+  border: 1px solid var(--color-surface-400);
+  border-radius: var(--radius-2);
+  background: var(--color-surface-100);
+  box-shadow: var(--elevation-1);
+  display: flex;
+  flex-direction: column;
+}
+
+.solara-datepicker__month-grid,
+.solara-datepicker__year-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: calc(var(--space-1) * var(--spacing-multiplier));
+}
+
+.solara-datepicker__year-nav {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: calc(var(--space-2) * var(--spacing-multiplier));
+}
+
+.solara-datepicker__year-nav-label {
+  font-size: var(--font-size-footnote-scaled);
+  color: var(--color-text-secondary);
+}
+
+.solara-datepicker__panel-nav-button,
+.solara-datepicker__panel-option {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  min-height: 2rem;
+  border: 1px solid var(--color-surface-400);
+  border-radius: var(--radius-2);
+  background: var(--color-surface-100);
+  color: var(--color-text-primary);
+  cursor: pointer;
+}
+
+.solara-datepicker__panel-nav-button {
+  width: 2rem;
+  min-height: 2rem;
+}
+
+.solara-datepicker__panel-option {
+  font-size: var(--font-size-footnote-scaled);
+
+  &:hover {
+    background: var(--color-surface-200);
+  }
+}
+
+.solara-datepicker__panel-option--active {
+  border-color: color-mix(in srgb, var(--datepicker-accent) 55%, var(--color-surface-400));
+  background: var(--datepicker-accent-muted);
+}
+
+.solara-datepicker__dropdowns {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: calc(var(--space-2) * var(--spacing-multiplier));
+  font-size: var(--font-size-caption-scaled);
+  font-weight: 500;
+}
+
+.solara-datepicker__dropdown-root {
+  position: relative;
+  border: 1px solid var(--color-surface-400);
+  border-radius: var(--radius-2);
+  background: var(--color-surface-100);
+  box-shadow: var(--elevation-1);
+}
+
+.solara-datepicker__dropdown {
+  position: absolute;
+  inset: 0;
+  opacity: 0;
+}
+
+.solara-datepicker__caption-label {
+  font-size: var(--font-size-caption-scaled);
+  font-weight: 500;
+  color: var(--color-text-primary);
+}
+
+.solara-datepicker__table {
+  grid-row: 2;
+  grid-column: 1;
+  width: 100%;
+  min-height: var(--datepicker-body-min-height);
+  border-collapse: collapse;
+}
+
+.solara-datepicker__weekdays {
+  display: flex;
+}
+
+.solara-datepicker__weekday {
+  flex: 1;
+  text-align: center;
+  font-size: var(--font-size-footnote-scaled);
+  color: var(--color-text-tertiary);
+  border-radius: var(--radius-2);
+}
+
+.solara-datepicker__week {
+  display: flex;
+  width: 100%;
+  margin-top: calc(var(--space-2) * var(--spacing-multiplier));
+}
+
+.solara-datepicker__day {
+  position: relative;
+  flex: 1;
+}
+
+.solara-datepicker__day-button {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  aspect-ratio: 1 / 1;
+  min-width: var(--datepicker-cell-size);
+  border-radius: var(--radius-2);
+  border: 1px solid transparent;
+  color: var(--color-text-secondary);
+  background: transparent;
+  transition: background-color 0.2s ease, transform 0.2s ease, box-shadow 0.2s ease;
+
+  &:hover {
+    background: var(--color-surface-200);
+  }
+
+  &:focus-visible {
+    outline: none;
+    box-shadow: 0 0 0 3px var(--color-focus-halo);
+  }
+}
+
+.solara-datepicker__today {
+  border: 1px solid var(--color-divider-accent);
+  border-radius: var(--radius-2);
+}
+
+.solara-datepicker__selected {
+  background: var(--datepicker-accent);
+  color: var(--color-text-inverse);
+  border-radius: var(--radius-2);
+  border: 1px solid transparent;
+
+  &:hover {
+    background: color-mix(in srgb, var(--datepicker-accent) 90%, var(--color-surface-0));
+    color: var(--color-text-inverse);
+  }
+}
+
+.solara-datepicker__today.solara-datepicker__selected {
+  border-color: transparent;
+}
+
+.solara-datepicker__range-start {
+  background: var(--datepicker-accent);
+  color: var(--color-text-inverse);
+  border-top-left-radius: var(--radius-2);
+  border-bottom-left-radius: var(--radius-2);
+}
+
+.solara-datepicker__range-middle {
+  background: var(--datepicker-accent-muted);
+  color: var(--color-text-primary);
+  border-radius: 0;
+}
+
+.solara-datepicker__range-end {
+  background: var(--datepicker-accent);
+  color: var(--color-text-inverse);
+  border-top-right-radius: var(--radius-2);
+  border-bottom-right-radius: var(--radius-2);
+}
+
+.solara-datepicker__outside {
+  color: var(--color-text-tertiary);
+}
+
+.solara-datepicker__disabled {
+  color: var(--color-text-tertiary);
+  opacity: 0.5;
+}
+
+.solara-datepicker__hidden {
+  visibility: hidden;
+}
+
+.solara-datepicker__week-number-cell {
+  display: flex;
+  width: var(--datepicker-cell-size);
+  height: var(--datepicker-cell-size);
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  color: var(--color-text-tertiary);
+  font-size: var(--font-size-footnote-scaled);
+}
+
+.solara-datepicker__chevron {
+  display: inline-flex;
+  font-size: 0.9em;
+  line-height: 1;
+}
+
+.solara-datepicker__menu {
+  --menu-padding: 0px;
+  min-width: 260px;
+}
+
+.solara-datepicker__trigger {
+  display: inline-flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: calc(var(--space-2) * var(--spacing-multiplier));
+  padding: calc(var(--space-2) * var(--spacing-multiplier))
+    calc(var(--space-3) * var(--spacing-multiplier));
+  border-radius: var(--radius-2);
+  border: 1px solid var(--color-surface-400);
+  background: var(--color-surface-100);
+  color: var(--color-text-primary);
+  font-family: var(--font-body);
+  font-size: var(--font-size-body-scaled);
+  line-height: var(--line-height-body-scaled);
+  cursor: pointer;
+  min-width: 220px;
+  transition: background-color 0.2s ease, border-color 0.2s ease, box-shadow 0.2s ease;
+
+  &:hover {
+    background: var(--color-surface-200);
+    border-color: var(--color-divider-accent);
+  }
+
+  &:focus-visible {
+    outline: none;
+    box-shadow: 0 0 0 3px var(--color-focus-halo);
+  }
+}
+
+.solara-datepicker__trigger-label {
+  display: inline-flex;
+  align-items: center;
+  gap: calc(var(--space-2) * var(--spacing-multiplier));
+}

package/src/DatePicker.tsx

@@ -0,0 +1,559 @@
+import React from "react";
+import { DayButton, DayPicker, getDefaultClassNames, useDayPicker } from "react-day-picker";
+import type { DateRange, Modifiers } from "react-day-picker";
+import type { CustomComponents } from "react-day-picker";
+import type { MonthCaptionProps } from "react-day-picker";
+import { Menu, MenuDropdown } from "@solara/menu";
+import type { MenuDropdownProps } from "@solara/menu";
+import type { DatePickerPanelProps, DatePickerProps, DatePickerSelection } from "./DatePicker.types";
+import "./DatePicker.scss";
+
+const DEFAULT_PLACEHOLDER = "Select date";
+type DatePickerHeaderPanel = "month" | "year" | null;
+const YEAR_PAGE_SIZE = 12;
+const YEAR_PAGE_CENTER_OFFSET = 6;
+
+type DatePickerHeaderViewState = {
+  // Which alternate body view is active under the header.
+  activePanel: DatePickerHeaderPanel;
+  setActivePanel: React.Dispatch<React.SetStateAction<DatePickerHeaderPanel>>;
+  // First visible year in the paged year grid.
+  yearPageStart: number;
+  setYearPageStart: React.Dispatch<React.SetStateAction<number>>;
+};
+
+const DatePickerHeaderViewContext = React.createContext<DatePickerHeaderViewState | null>(null);
+
+function getCenteredYearPageStart(year: number) {
+  return year - YEAR_PAGE_CENTER_OFFSET;
+}
+
+function getYearPageOptions(yearPageStart: number) {
+  return Array.from({ length: YEAR_PAGE_SIZE }, (_, i) => yearPageStart + i);
+}
+
+const DEFAULT_CLASSNAMES = {
+  root: "solara-datepicker",
+  months: "solara-datepicker__months",
+  month: "solara-datepicker__month",
+  nav: "solara-datepicker__nav",
+  button_previous: "solara-datepicker__nav-button",
+  button_next: "solara-datepicker__nav-button",
+  month_caption: "solara-datepicker__caption",
+  dropdowns: "solara-datepicker__dropdowns",
+  dropdown_root: "solara-datepicker__dropdown-root",
+  dropdown: "solara-datepicker__dropdown",
+  caption_label: "solara-datepicker__caption-label",
+  table: "solara-datepicker__table",
+  weekdays: "solara-datepicker__weekdays",
+  weekday: "solara-datepicker__weekday",
+  week: "solara-datepicker__week",
+  week_number_header: "solara-datepicker__week-number-header",
+  week_number: "solara-datepicker__week-number",
+  day: "solara-datepicker__day",
+  today: "solara-datepicker__today",
+  outside: "solara-datepicker__outside",
+  disabled: "solara-datepicker__disabled",
+  hidden: "solara-datepicker__hidden",
+  selected: "solara-datepicker__selected",
+  range_start: "solara-datepicker__range-start",
+  range_middle: "solara-datepicker__range-middle",
+  range_end: "solara-datepicker__range-end",
+};
+
+function cx(...values: Array<string | false | null | undefined>) {
+  return values.filter(Boolean).join(" ");
+}
+
+function formatSelectedLabel(value: DatePickerSelection) {
+  if (!value) return null;
+  if (value instanceof Date) return value.toLocaleDateString();
+  if (Array.isArray(value)) {
+    if (value.length === 0) return null;
+    if (value.length === 1) return value[0]?.toLocaleDateString();
+    const first = value[0];
+    const last = value[value.length - 1];
+    if (!first || !last) return null;
+    return `${first.toLocaleDateString()} – ${last.toLocaleDateString()}`;
+  }
+
+  const range = value as DateRange;
+  if (range?.from && range?.to) {
+    return `${range.from.toLocaleDateString()} – ${range.to.toLocaleDateString()}`;
+  }
+  if (range?.from) {
+    return range.from.toLocaleDateString();
+  }
+  return null;
+}
+
+function useControllableOpenState({
+  isOpen,
+  defaultOpen,
+  onOpenChange,
+}: Pick<DatePickerProps, "isOpen" | "defaultOpen" | "onOpenChange">) {
+  // Support controlled and uncontrolled open state with one hook.
+  const [uncontrolledOpen, setUncontrolledOpen] = React.useState(Boolean(defaultOpen));
+  const open = isOpen ?? uncontrolledOpen;
+
+  const setOpen = React.useCallback(
+    (next: boolean) => {
+      if (isOpen === undefined) setUncontrolledOpen(next);
+      onOpenChange?.(next);
+    },
+    [isOpen, onOpenChange]
+  );
+
+  return [open, setOpen] as const;
+}
+
+export function DatePickerPanel({
+  className,
+  variant = "standalone",
+  mode = "single",
+  showOutsideDays = true,
+  captionLayout = "label",
+  navLayout = "around",
+  hideNavigation = true,
+  formatters,
+  components,
+  classNames,
+  ...props
+}: DatePickerPanelProps) {
+  // Header-level state drives the "swap the calendar body" behavior.
+  const [activePanel, setActivePanel] = React.useState<DatePickerHeaderPanel>(null);
+  const [yearPageStart, setYearPageStart] = React.useState(
+    getCenteredYearPageStart(new Date().getFullYear())
+  );
+  const defaultClassNames = React.useMemo(() => getDefaultClassNames(), []);
+  const mergedFormatters = React.useMemo(
+    () => ({
+      formatMonthDropdown: (date: Date) => date.toLocaleString("default", { month: "short" }),
+      ...formatters,
+    }),
+    [formatters]
+  );
+  const mergedClassNames = React.useMemo(
+    () => ({
+      root: cx(DEFAULT_CLASSNAMES.root, defaultClassNames.root),
+      months: cx(DEFAULT_CLASSNAMES.months, defaultClassNames.months),
+      month: cx(DEFAULT_CLASSNAMES.month, defaultClassNames.month),
+      nav: cx(DEFAULT_CLASSNAMES.nav, defaultClassNames.nav),
+      button_previous: cx(DEFAULT_CLASSNAMES.button_previous, defaultClassNames.button_previous),
+      button_next: cx(DEFAULT_CLASSNAMES.button_next, defaultClassNames.button_next),
+      month_caption: cx(DEFAULT_CLASSNAMES.month_caption, defaultClassNames.month_caption),
+      dropdowns: cx(DEFAULT_CLASSNAMES.dropdowns, defaultClassNames.dropdowns),
+      dropdown_root: cx(DEFAULT_CLASSNAMES.dropdown_root, defaultClassNames.dropdown_root),
+      dropdown: cx(DEFAULT_CLASSNAMES.dropdown, defaultClassNames.dropdown),
+      caption_label: cx(DEFAULT_CLASSNAMES.caption_label, defaultClassNames.caption_label),
+      table: cx(DEFAULT_CLASSNAMES.table),
+      weekdays: cx(DEFAULT_CLASSNAMES.weekdays, defaultClassNames.weekdays),
+      weekday: cx(DEFAULT_CLASSNAMES.weekday, defaultClassNames.weekday),
+      week: cx(DEFAULT_CLASSNAMES.week, defaultClassNames.week),
+      week_number_header: cx(
+        DEFAULT_CLASSNAMES.week_number_header,
+        defaultClassNames.week_number_header
+      ),
+      week_number: cx(DEFAULT_CLASSNAMES.week_number, defaultClassNames.week_number),
+      day: cx(DEFAULT_CLASSNAMES.day, defaultClassNames.day),
+      today: cx(DEFAULT_CLASSNAMES.today, defaultClassNames.today),
+      outside: cx(DEFAULT_CLASSNAMES.outside, defaultClassNames.outside),
+      disabled: cx(DEFAULT_CLASSNAMES.disabled, defaultClassNames.disabled),
+      hidden: cx(DEFAULT_CLASSNAMES.hidden, defaultClassNames.hidden),
+      selected: cx(DEFAULT_CLASSNAMES.selected, defaultClassNames.selected),
+      range_start: cx(DEFAULT_CLASSNAMES.range_start, defaultClassNames.range_start),
+      range_middle: cx(DEFAULT_CLASSNAMES.range_middle, defaultClassNames.range_middle),
+      range_end: cx(DEFAULT_CLASSNAMES.range_end, defaultClassNames.range_end),
+      ...classNames,
+    }),
+    [classNames, defaultClassNames]
+  );
+  const mergedComponents = React.useMemo<Partial<CustomComponents>>(() => {
+    // Root wrapper keeps Solara variant data attributes on the DayPicker root.
+    const Root: CustomComponents["Root"] = ({ className: rootClassName, rootRef, ...rootProps }) => (
+      <div
+        data-slot="datepicker"
+        data-variant={variant}
+        ref={rootRef}
+        className={cx(rootClassName)}
+        {...rootProps}
+      />
+    );
+    const Chevron: CustomComponents["Chevron"] = ({
+      className: chevronClassName,
+      orientation,
+      ...chevronProps
+    }) => (
+      <span
+        aria-hidden
+        className={cx("solara-datepicker__chevron", chevronClassName)}
+        data-orientation={orientation}
+        {...chevronProps}>
+        {orientation === "left" ? "‹" : orientation === "right" ? "›" : "▾"}
+      </span>
+    );
+    const WeekNumber: CustomComponents["WeekNumber"] = ({ children, ...weekProps }) => (
+      <td {...weekProps}>
+        <div className="solara-datepicker__week-number-cell">{children}</div>
+      </td>
+    );
+    // Keep the top caption/header mounted; only swap the body area between
+    // day-grid vs month/year grids.
+    const MonthGrid: CustomComponents["MonthGrid"] = ({ children, className }) =>
+      activePanel ? (
+        <div
+          className={cx("solara-datepicker__caption-panel", className)}
+          role="region">
+          <DatePickerHeaderPanelView />
+        </div>
+      ) : (
+        <table className={className}>{children}</table>
+      );
+
+    return {
+      Root,
+      Chevron,
+      // Custom caption owns the header controls and active panel toggles.
+      MonthCaption: DatePickerMonthCaption,
+      MonthGrid,
+      DayButton: DatePickerDayButton,
+      WeekNumber,
+      ...components,
+    };
+  }, [activePanel, components, variant]);
+
+  const dayPickerProps = {
+    mode,
+    showOutsideDays,
+    captionLayout,
+    navLayout,
+    hideNavigation,
+    formatters: mergedFormatters,
+    className,
+    classNames: mergedClassNames,
+    components: mergedComponents,
+    ...props,
+  } as React.ComponentProps<typeof DayPicker>;
+
+  return (
+    // Expose header mode state to both caption (top controls) and body swapper.
+    <DatePickerHeaderViewContext.Provider
+      value={{
+        activePanel,
+        setActivePanel,
+        yearPageStart,
+        setYearPageStart,
+      }}>
+      <DayPicker {...dayPickerProps} />
+    </DatePickerHeaderViewContext.Provider>
+  );
+}
+
+export function DatePicker({
+  trigger,
+  placeholder = DEFAULT_PLACEHOLDER,
+  formatLabel,
+  align = "start",
+  side = "bottom",
+  isOpen,
+  defaultOpen,
+  onOpenChange,
+  closeOnSelect = true,
+  menuProps,
+  contentAriaLabel = "Date picker",
+  triggerClassName,
+  ...panelProps
+}: DatePickerProps) {
+  const [open, setOpen] = useControllableOpenState({
+    isOpen,
+    defaultOpen,
+    onOpenChange,
+  });
+
+  const { selected, onSelect } = panelProps as DatePickerPanelProps as {
+    selected?: DatePickerSelection;
+    onSelect?: (
+      selected: DatePickerSelection,
+      triggerDate: Date,
+      modifiers: Modifiers,
+      e: React.MouseEvent | React.KeyboardEvent
+    ) => void;
+  };
+  const selectionMode = (panelProps as DatePickerPanelProps).mode ?? "single";
+  const selectedLabel = React.useMemo(
+    () => (formatLabel ?? formatSelectedLabel)(selected),
+    [formatLabel, selected]
+  );
+  const triggerLabel = selectedLabel ?? placeholder;
+
+  const mergedTrigger: MenuDropdownProps["trigger"] = React.useMemo(
+    () =>
+      trigger ??
+      (({ getTriggerProps }) => (
+        <button
+          {...getTriggerProps({
+            type: "button",
+            className: cx("solara-datepicker__trigger", triggerClassName),
+          })}>
+          <span className="solara-datepicker__trigger-label">{triggerLabel}</span>
+          <span aria-hidden className="solara-menu-trigger-chevron">
+            ▾
+          </span>
+        </button>
+      )),
+    [trigger, triggerClassName, triggerLabel]
+  );
+
+  const handleSelect = React.useCallback(
+    (
+      selected: DatePickerSelection,
+      triggerDate: Date,
+      modifiers: Modifiers,
+      e: React.MouseEvent | React.KeyboardEvent
+    ) => {
+      (onSelect as ((...args: unknown[]) => void) | undefined)?.(
+        selected,
+        triggerDate,
+        modifiers,
+        e
+      );
+      // Caller can opt out of automatic close behavior.
+      if (!closeOnSelect) return;
+      const selection = selected;
+      const isRangeSelection =
+        selectionMode === "range" ||
+        (selection && typeof selection === "object" && "from" in selection);
+      if (isRangeSelection) {
+        const range = selection as DateRange | undefined;
+        const hasCompleteRange = Boolean(range?.from && range?.to);
+        const isSingleDayRange = Boolean(
+          range?.from && range?.to && range.from.getTime() === range.to.getTime()
+        );
+        // Close only when the range is complete and spans at least 2 days.
+        if (hasCompleteRange && !isSingleDayRange) setOpen(false);
+        return;
+      }
+      // Multiple mode stays open for additional picks.
+      if (selectionMode === "multiple") return;
+      // Single mode closes after selection.
+      setOpen(false);
+    },
+    [onSelect, closeOnSelect, selectionMode, setOpen]
+  );
+
+  return (
+    <MenuDropdown
+      trigger={mergedTrigger}
+      align={align}
+      side={side}
+      isOpen={open}
+      onOpenChange={setOpen}
+      closeOnSelect={false}
+      contentAriaLabel={contentAriaLabel}>
+      <Menu
+        {...menuProps}
+        className={cx("solara-datepicker__menu", menuProps?.className)}>
+        <DatePickerPanel
+          {...panelProps}
+          variant="menu"
+          onSelect={handleSelect}
+        />
+      </Menu>
+    </MenuDropdown>
+  );
+}
+
+function DatePickerDayButton({
+  className,
+  day,
+  modifiers,
+  ...props
+}: React.ComponentProps<typeof DayButton>) {
+  const defaultClassNames = getDefaultClassNames();
+  const ref = React.useRef<HTMLButtonElement>(null);
+
+  React.useEffect(() => {
+    // Preserve keyboard focus behavior expected by DayPicker.
+    if (modifiers.focused) ref.current?.focus();
+  }, [modifiers.focused]);
+
+  return (
+    <button
+      ref={ref}
+      data-day={day.date.toLocaleDateString()}
+      data-selected={modifiers.selected ? "true" : "false"}
+      className={cx("solara-datepicker__day-button", defaultClassNames.day, className)}
+      {...props}
+    />
+  );
+}
+
+function DatePickerMonthCaption({
+  calendarMonth,
+  displayIndex: _displayIndex,
+  className,
+  ...props
+}: MonthCaptionProps) {
+  // Header owns month navigation and mode toggles.
+  const { goToMonth, previousMonth, nextMonth } = useDayPicker();
+  const headerView = React.useContext(DatePickerHeaderViewContext);
+  if (!headerView) {
+    return (
+      <div
+        className={cx("solara-datepicker__caption", className)}
+        {...props}
+      />
+    );
+  }
+  const { activePanel, setActivePanel, setYearPageStart } = headerView;
+
+  const monthDate = calendarMonth.date;
+  const monthIndex = monthDate.getMonth();
+  const year = monthDate.getFullYear();
+  const monthLabel = monthDate.toLocaleString("default", { month: "long" });
+  const yearLabel = String(year);
+
+  React.useEffect(() => {
+    // Recenter the year page whenever the visible year changes.
+    if (activePanel === "year") setYearPageStart(getCenteredYearPageStart(year));
+  }, [activePanel, setYearPageStart, year]);
+
+  const togglePanel = React.useCallback(
+    (panel: Exclude<DatePickerHeaderPanel, null>) => {
+      // Clicking the active mode again returns to the default day grid.
+      setActivePanel((prev) => (prev === panel ? null : panel));
+    },
+    [setActivePanel]
+  );
+
+  return (
+    <div
+      className={cx("solara-datepicker__caption", className)}
+      {...props}>
+      <div className="solara-datepicker__caption-controls">
+        <button
+          type="button"
+          className="solara-datepicker__header-nav-button"
+          onClick={() => previousMonth && goToMonth(previousMonth)}
+          disabled={!previousMonth}
+          aria-label="Go to previous month">
+          ‹
+        </button>
+        <div className="solara-datepicker__caption-title-buttons">
+          <button
+            type="button"
+            className={cx(
+              "solara-datepicker__caption-button",
+              activePanel === "month" && "solara-datepicker__caption-button--active"
+            )}
+            aria-haspopup="grid"
+            aria-expanded={activePanel === "month"}
+            onClick={() => togglePanel("month")}>
+            {monthLabel}
+          </button>
+          <button
+            type="button"
+            className={cx(
+              "solara-datepicker__caption-button",
+              activePanel === "year" && "solara-datepicker__caption-button--active"
+            )}
+            aria-haspopup="grid"
+            aria-expanded={activePanel === "year"}
+            onClick={() => togglePanel("year")}>
+            {yearLabel}
+          </button>
+        </div>
+        <button
+          type="button"
+          className="solara-datepicker__header-nav-button"
+          onClick={() => nextMonth && goToMonth(nextMonth)}
+          disabled={!nextMonth}
+          aria-label="Go to next month">
+          ›
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function DatePickerHeaderPanelView() {
+  // Body area switches between month/year grids while header stays fixed.
+  const { goToMonth, months } = useDayPicker();
+  const headerView = React.useContext(DatePickerHeaderViewContext);
+  if (!headerView) return null;
+
+  const { activePanel, setActivePanel, yearPageStart, setYearPageStart } = headerView;
+  const visibleMonth = months[0]?.date ?? new Date();
+  const monthIndex = visibleMonth.getMonth();
+  const year = visibleMonth.getFullYear();
+
+  if (!activePanel) return null;
+
+  // Selecting from month/year grids always updates visible month then returns
+  // to the default day-grid view.
+  const selectMonth = (nextMonthIndex: number) => {
+    goToMonth(new Date(year, nextMonthIndex, 1));
+    setActivePanel(null);
+  };
+
+  const selectYear = (nextYear: number) => {
+    goToMonth(new Date(nextYear, monthIndex, 1));
+    setActivePanel(null);
+  };
+
+  const yearOptions = getYearPageOptions(yearPageStart);
+
+  return activePanel === "month" ? (
+    <div className="solara-datepicker__month-grid" role="grid" aria-label="Choose month">
+      {Array.from({ length: 12 }, (_, i) => {
+        const label = new Date(year, i, 1).toLocaleString("default", { month: "short" });
+        return (
+          <button
+            key={label}
+            type="button"
+            className={cx(
+              "solara-datepicker__panel-option",
+              i === monthIndex && "solara-datepicker__panel-option--active"
+            )}
+            onClick={() => selectMonth(i)}>
+            {label}
+          </button>
+        );
+      })}
+    </div>
+  ) : (
+    <>
+      <div className="solara-datepicker__year-nav">
+        <button
+          type="button"
+          className="solara-datepicker__panel-nav-button"
+          onClick={() => setYearPageStart((prev) => prev - YEAR_PAGE_SIZE)}>
+          ‹
+        </button>
+        <span className="solara-datepicker__year-nav-label">
+          {yearPageStart} - {yearPageStart + (YEAR_PAGE_SIZE - 1)}
+        </span>
+        <button
+          type="button"
+          className="solara-datepicker__panel-nav-button"
+          onClick={() => setYearPageStart((prev) => prev + YEAR_PAGE_SIZE)}>
+          ›
+        </button>
+      </div>
+      <div className="solara-datepicker__year-grid" role="grid" aria-label="Choose year">
+        {yearOptions.map((optionYear) => (
+          <button
+            key={optionYear}
+            type="button"
+            className={cx(
+              "solara-datepicker__panel-option",
+              optionYear === year && "solara-datepicker__panel-option--active"
+            )}
+            onClick={() => selectYear(optionYear)}>
+            {optionYear}
+          </button>
+        ))}
+      </div>
+    </>
+  );
+}

package/src/DatePicker.types.ts

@@ -0,0 +1,100 @@
+import type {
+  DateRange,
+  OnSelectHandler,
+  PropsBase,
+  PropsMulti,
+  PropsMultiRequired,
+  PropsRange,
+  PropsRangeRequired,
+  PropsSingle,
+  PropsSingleRequired,
+} from "react-day-picker";
+import type { MenuDropdownProps, MenuProps } from "@solara/menu";
+
+export type DatePickerVariant = "menu" | "standalone";
+
+export type DatePickerSelection = Date | Date[] | DateRange | undefined;
+
+type DatePickerPanelBaseProps = Omit<PropsBase, "mode" | "required"> & {
+  /**
+   * Controls spacing + surface styling for the calendar surface.
+   */
+  variant?: DatePickerVariant;
+};
+
+type DatePickerSingleProps = Omit<PropsSingle, "mode"> & {
+  mode?: "single";
+};
+
+type DatePickerSingleRequiredProps = Omit<PropsSingleRequired, "mode"> & {
+  mode?: "single";
+};
+
+type DatePickerUncontrolledProps = {
+  mode?: undefined;
+  required?: undefined;
+  selected?: undefined;
+  onSelect?: OnSelectHandler<DatePickerSelection>;
+};
+
+export type DatePickerPanelProps = DatePickerPanelBaseProps &
+  (
+    | DatePickerSingleProps
+    | DatePickerSingleRequiredProps
+    | PropsMulti
+    | PropsMultiRequired
+    | PropsRange
+    | PropsRangeRequired
+    | DatePickerUncontrolledProps
+  );
+
+export type DatePickerProps = DatePickerPanelProps & {
+  /**
+   * Optional trigger to open the date picker menu.
+   */
+  trigger?: MenuDropdownProps["trigger"];
+  /**
+   * Placeholder label used by the default trigger.
+   */
+  placeholder?: string;
+  /**
+   * Format the selected value into a trigger label.
+   */
+  formatLabel?: (value: DatePickerSelection) => string;
+  /**
+   * Menu placement (align) for the dropdown.
+   */
+  align?: MenuDropdownProps["align"];
+  /**
+   * Menu placement (side) for the dropdown.
+   */
+  side?: MenuDropdownProps["side"];
+  /**
+   * Controlled open state for the dropdown.
+   */
+  isOpen?: MenuDropdownProps["isOpen"];
+  /**
+   * Default open state for the dropdown.
+   */
+  defaultOpen?: MenuDropdownProps["defaultOpen"];
+  /**
+   * Notify when the dropdown opens or closes.
+   */
+  onOpenChange?: MenuDropdownProps["onOpenChange"];
+  /**
+   * Close the dropdown when a date is selected.
+   */
+  closeOnSelect?: boolean;
+  /**
+   * Props passed to the Menu surface wrapper.
+   */
+  menuProps?: Omit<MenuProps, "children">;
+  /**
+   * Accessible label for the dropdown content.
+   */
+  contentAriaLabel?: MenuDropdownProps["contentAriaLabel"];
+  /**
+   * Custom class name for the trigger button.
+   */
+  triggerClassName?: string;
+};

package/src/index.ts

@@ -0,0 +1,2 @@
+export { DatePicker, DatePickerPanel } from "./DatePicker";
+export type { DatePickerProps, DatePickerPanelProps, DatePickerVariant } from "./DatePicker.types";