@vvedantb/ui 0.13.0 → 0.14.0

package/README.md

@@ -4,7 +4,7 @@ Shared React 19 web UI. Source-exported: no build step.
 
 | Import | What it is |
 | --- | --- |
-| `@vvedantb/ui` | The only JavaScript entry. Primitives (Radix-based), AI elements, audio (`playChime`, `useReplyChime`, `playTone`), `toast` and `SonnerToaster`, the composer (`InputArea`, deprecated 0.3 `Composer`), shell (`SidebarHeader`, `PillTabs`, `SessionsHoverCard`, and the app shell: `AppShell`, `AppSidebar`, `SidebarRail`, `RailTile`, `SidebarPanel`, `SidebarAccountMenu`, `SignOutDialog` and related helpers), app helpers (confirm skip, update watcher, settings chrome, `useStableAuth`, and from 0.8.0 `createThemeProvider`, `createPageTitleContext`, `PageMotionProvider` and `formatCompactRelativeTime`), marketing pieces from 0.9.0 (`createLandingKit` and the `Landing*` parts, `SiteFooter`, `PricingModal`), animated nav icons from 0.11.0 (`MemoryIcon`, `BoardIcon`, ... and `NavIconBase`; `SettingsIcon` `variant` from 0.12.0), artifact viewers from 0.13.0 (`ArtifactFrame`, `ArtifactList`, `ArtifactViewer`, ...), `cn`, and the native tokens `tokens` and `Tokens`. See `app/README.md` in the repository for the app helpers. |
+| `@vvedantb/ui` | The only JavaScript entry. Primitives (Radix-based), AI elements, audio (`playChime`, `useReplyChime`, `playTone`), `toast` and `SonnerToaster`, the composer (`InputArea`, deprecated 0.3 `Composer`), shell (`SidebarHeader`, `PillTabs`, `SessionsHoverCard`, and the app shell: `AppShell`, `AppSidebar`, `SidebarRail`, `RailTile`, `SidebarPanel`, `SidebarAccountMenu`, `SignOutDialog` and related helpers), app helpers (confirm skip, update watcher, settings chrome, `useStableAuth`, and from 0.8.0 `createThemeProvider`, `createPageTitleContext`, `PageMotionProvider` and `formatCompactRelativeTime`), marketing pieces from 0.9.0 (`createLandingKit` and the `Landing*` parts, `SiteFooter`, `PricingModal`), animated nav icons from 0.11.0 (`MemoryIcon`, `BoardIcon`, ... and `NavIconBase`; `SettingsIcon` `variant` from 0.12.0), artifact viewers from 0.13.0 (`ArtifactFrame`, `ArtifactList`, `ArtifactViewer`, ...), date pickers from 0.14.0 (`Calendar`, `DatePicker`, `DateTimePicker`, `MonthPicker`), `cn`, and the native tokens `tokens` and `Tokens`. See `app/README.md` in the repository for the app helpers. |
 | `@vvedantb/ui/tokens` | `tokens.css`: colour, radius, shadow, ease and font tokens for Tailwind v4. CSS. |
 | `@vvedantb/ui/tokens/tokens.css` | Same file as `@vvedantb/ui/tokens`. CSS. |
 | `@vvedantb/ui/tokens/css/*.css` | `index`, `base`, `dialog`, `modal`, `tabs`, `tabs-pills`, `utilities`, `scrollbar-thin`, `animations`, `nav-icons`, `compat-shadcn-rgb`. CSS. |
@@ -982,9 +982,26 @@ const store: ArtifactStateStore = {
 - `ArtifactListToolbar`: controlled `ToolbarSearchInput` (`query`, `onQueryChange`), a type filter menu (`type`, `onTypeChange`, `types`; `undefined` is "All types") and a grid or list toggle (`layout`, `onLayoutChange`). The filter and the toggle show only with their callbacks. `children` go at the end.
 - `ArtifactViewer`: the ai-elements `Artifact` container with a header (`headerStart`, type icon, title) and actions: versions menu (`versions`), Rename, Copy, Download (the format's extension and MIME type from `ARTIFACT_FORMAT_FILES`), Open in new tab (`href`), your `actions`, and Delete. Below it, `ArtifactRender` of `artifact.body`. Pass the body of the version on screen.
 - `ArtifactVersionsMenu`: a "vN" button listing `versions` newest first, with the current one marked. With `onViewVersion`, picking a version shows it, and "Restore vN" (`onRestoreVersion`) appears while an older version is on screen. Without it, picking an older version restores it.
-- Rename and delete use `ConfirmDialog` (`ArtifactRenameDialog`, `ArtifactDeleteDialog`, and `useArtifactEditDialogs` for custom surfaces). Rename sends the trimmed title, and does nothing when it is unchanged. Alt-click on Delete skips the dialog, as with `useRequestConfirm`. A callback that rejects keeps its dialog open and shows an error toast; copy and load failures toast too, so mount `SonnerToaster`.
+- Rename and delete use `ConfirmDialog` (`ArtifactRenameDialog`, `ArtifactDeleteDialog`, and `useArtifactEditDialogs` for custom surfaces). Rename sends the trimmed title, and does nothing when it is unchanged. Alt-click on Delete skips the dialog, as with `useRequestConfirm`. The delete dialog says "This cannot be undone."; pass `deleteDescription` to `ArtifactViewer`, `ArtifactCard` or `ArtifactList` to change it (0.13.1), for example when your delete can be undone. A callback that rejects keeps its dialog open and shows an error toast; copy and load failures toast too, so mount `SonnerToaster`.
 - `ArtifactTypeIcon` (`type`, `size`, `stroke`) and `ARTIFACT_TYPE_LABELS` (`mindmap` is "Mind map"). Helpers `downloadArtifactBody(title, format, body)`, `copyArtifactBody(body)`, `openArtifactInNewTab(href)`. Row types: `ArtifactSummary` (any `ArtifactListRow` fits), `ArtifactDocument`, `ArtifactVersionSummary`.
 
+## Date pickers (0.14.0)
+
+Controlled pickers that read and write the native input strings, as local calendar dates with no timezone logic. They need `react-day-picker` 9, a dependency of this package.
+
+```tsx
+import { DatePicker, DateTimePicker, MonthPicker } from "@vvedantb/ui";
+
+<DatePicker value={due} onChange={setDue} min="2026-01-01" clearable name="due" ariaLabel="Due date" />
+<DateTimePicker value={startsAt} onChange={setStartsAt} defaultTime="09:00" name="startsAt" />
+<MonthPicker value={month} onChange={setMonth} max="2026-12" />
+```
+
+- `DatePicker`: `value` "YYYY-MM-DD" or "". The trigger matches `TimePicker` and shows the date with `dateStyle: "medium"` (`locale`) or `placeholder` ("Pick a date"). `min` and `max` disable days; `clearable` adds a clear control (`onChange("")`); `name` adds a hidden input. `className` goes on the wrapper, `triggerClassName` merges onto the button (default `w-40`). A width on either sizes the field, and `w-full` on either fills the row; pill inputs can pass `triggerClassName="h-10 w-full rounded-full px-4 text-sm"`. `ariaLabel` names the trigger, followed by the shown text.
+- `DateTimePicker`: `value` "YYYY-MM-DDTHH:mm" or "". A date with no time uses `defaultTime` ("00:00"); a time with no date uses today. Only the date part of `min` and `max` applies. `triggerClassName` goes to both triggers, a width only to the date.
+- `MonthPicker`: `value` "YYYY-MM" or "", with year navigation and a month grid. `min` and `max` are "YYYY-MM".
+- `Calendar`: the styled `DayPicker` for custom layouts (every `DayPicker` prop). `parseDateValue` and `formatDateValue` convert between "YYYY-MM-DD" and a local `Date`.
+
 ## Toaster
 
 ```tsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "license": "MIT",
   "description": "Shared React 19 UI for web apps: one JavaScript entry (primitives, shell pieces, app helpers including the Convex and Clerk provider, VITE env parsing and ensure-user, artifact viewers over the @vvedantb/server artifacts core, native tokens), design-token CSS, shared Tailwind v4 CSS and a Tailwind preset.",
   "type": "module",
@@ -64,6 +64,9 @@
     "analyze": "node tokens/verify/analyze.mjs",
     "prepack": "node tokens/scripts/check-exports.mjs"
   },
+  "dependencies": {
+    "react-day-picker": "^9.14.0"
+  },
   "peerDependencies": {
     "@clerk/clerk-react": ">=5",
     "@radix-ui/react-accordion": "^1.2.12",

package/src/artifacts/artifact-card.tsx

@@ -33,6 +33,8 @@ export type ArtifactCardActions = {
   onRename?: (artifact: ArtifactSummary, title: string) => void | Promise<void>;
   /** Called after the delete dialog, or straight away on an Alt-click. */
   onDelete?: (artifact: ArtifactSummary) => void | Promise<void>;
+  /** Text under the delete dialog's title, e.g. for a host that can undo. Defaults to "This cannot be undone." */
+  deleteDescription?: ReactNode;
 };
 
 export type ArtifactCardProps = ArtifactCardActions & {
@@ -69,12 +71,14 @@ export function ArtifactCard({
   getBody,
   onRename,
   onDelete,
+  deleteDescription,
   className,
 }: ArtifactCardProps) {
   const edit = useArtifactEditDialogs({
     title: artifact.title,
     onRename: onRename && ((title) => onRename(artifact, title)),
     onDelete: onDelete && (() => onDelete(artifact)),
+    deleteDescription,
   });
   const href = getHref?.(artifact);
 

package/src/artifacts/artifact-dialogs.tsx

@@ -51,16 +51,25 @@ export type ArtifactDeleteDialogProps = {
   title: string;
   onConfirm: () => void;
   pending?: boolean;
+  /** Text under the title. Defaults to "This cannot be undone." */
+  description?: ReactNode;
 };
 
 /** "Delete <title>?" confirmation. Cancel is focused on open. */
-export function ArtifactDeleteDialog({ open, onOpenChange, title, onConfirm, pending }: ArtifactDeleteDialogProps) {
+export function ArtifactDeleteDialog({
+  open,
+  onOpenChange,
+  title,
+  onConfirm,
+  pending,
+  description = "This cannot be undone.",
+}: ArtifactDeleteDialogProps) {
   return (
     <ConfirmDialog.Root alert={false} focusCancel pending={pending} open={open} onOpenChange={onOpenChange}>
       <ConfirmDialog.Content className="max-w-sm" role="alertdialog">
         <ConfirmDialog.Header>
           <ConfirmDialog.Title>Delete &quot;{title}&quot;?</ConfirmDialog.Title>
-          <ConfirmDialog.Description>This cannot be undone.</ConfirmDialog.Description>
+          <ConfirmDialog.Description>{description}</ConfirmDialog.Description>
         </ConfirmDialog.Header>
         <ConfirmDialog.Footer>
           <ConfirmDialog.Cancel variant="secondary" />
@@ -78,13 +87,15 @@ export type ArtifactEditCallbacks = {
   onRename?: (title: string) => void | Promise<void>;
   /** Called after the delete dialog, or straight away on an Alt-click. */
   onDelete?: () => void | Promise<void>;
+  /** Text under the delete dialog's title, e.g. for a host that can undo. Defaults to "This cannot be undone." */
+  deleteDescription?: ReactNode;
 };
 
 /**
  * Rename and delete dialog state shared by the card and the viewer. `dialogs`
  * must be rendered; `requestDelete(event)` skips the dialog on an Alt-click.
  */
-export function useArtifactEditDialogs({ title, onRename, onDelete }: ArtifactEditCallbacks & { title: string }) {
+export function useArtifactEditDialogs({ title, onRename, onDelete, deleteDescription }: ArtifactEditCallbacks & { title: string }) {
   const [renameOpen, setRenameOpen] = useState(false);
   const [renameValue, setRenameValue] = useState(title);
   const [deleteOpen, setDeleteOpen] = useState(false);
@@ -137,6 +148,7 @@ export function useArtifactEditDialogs({ title, onRename, onDelete }: ArtifactEd
           title={title}
           onConfirm={remove}
           pending={pending}
+          description={deleteDescription}
         />
       ) : null}
     </>

package/src/artifacts/artifact-viewer.tsx

@@ -45,11 +45,12 @@ export function ArtifactViewer({
   href,
   onRename,
   onDelete,
+  deleteDescription,
   headerStart,
   actions,
   className,
 }: ArtifactViewerProps) {
-  const edit = useArtifactEditDialogs({ title: artifact.title, onRename, onDelete });
+  const edit = useArtifactEditDialogs({ title: artifact.title, onRename, onDelete, deleteDescription });
   const extension = ARTIFACT_FORMAT_FILES[artifact.format].extension;
   const actionClass = "h-8 min-w-8";
 

package/src/index.ts

@@ -55,6 +55,8 @@ export * from "./ui/tabs";
 export * from "./ui/textarea";
 export * from "./ui/toolbar-search-input";
 export * from "./ui/time-picker";
+export * from "./ui/calendar";
+export * from "./ui/date-picker";
 export * from "./ui/tooltip";
 export * from "./ui/kbd";
 export * from "./ui/sheet";

package/src/ui/_picker-classes.ts

@@ -0,0 +1,18 @@
+// input-styled trigger shared by TimePicker and the date pickers
+export const pickerTriggerClass =
+  "inline-flex h-8 items-center justify-between gap-2 rounded-field border border-border bg-field-background px-2.5 text-xs font-medium tabular-nums transition-[border-color,box-shadow,background-color] duration-200 ease-smooth hover:bg-field-background/90 focus-visible:border-focus-border focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring disabled:cursor-not-allowed disabled:opacity-50";
+
+// selected item in a picker popover (TimePicker columns, calendar days, months)
+export const pickerSelectedClass = "bg-primary text-primary-foreground";
+
+export const pickerItemHoverClass = "hover:bg-surface-tertiary/50";
+
+export const pickerFocusClass =
+  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring";
+
+// wrapper around a trigger and its siblings (clear control, second picker). it
+// shrinks to the trigger, grows with a `w-*` className, and goes full width
+// when a trigger inside is `w-full` (a percent width cannot resolve against a
+// shrink-to-fit wrapper)
+export const pickerFieldClass =
+  "relative inline-flex max-w-full align-middle has-[.w-full]:flex has-[.w-full]:w-full";

package/src/ui/calendar.tsx

@@ -0,0 +1,161 @@
+import * as React from "react";
+import {
+  IconChevronDown,
+  IconChevronLeft,
+  IconChevronRight,
+} from "@tabler/icons-react";
+import {
+  type Chevron,
+  DayPicker,
+  type Root,
+  getDefaultClassNames,
+} from "react-day-picker";
+import { cn } from "../utils/cn";
+import {
+  pickerFocusClass,
+} from "./_picker-classes";
+
+// shadcn's v9 calendar on package tokens: no background of its own (it takes
+// the popover or card surface it sits on), selected days use the picker
+// active treatment, today gets a dot, outside days are muted and disabled
+// days dimmed. day state lives on the cell (`data-selected`, `data-today`,
+// ...), so the day button reads it through `group/day`
+const navButtonClass = cn(
+  "inline-flex size-(--cell-size) select-none items-center justify-center rounded-lg p-0 text-muted-foreground transition-colors hover:bg-surface-tertiary hover:text-foreground aria-disabled:pointer-events-none aria-disabled:opacity-50",
+  pickerFocusClass,
+);
+
+function CalendarRoot({
+  className,
+  rootRef,
+  ...props
+}: React.ComponentProps<typeof Root>) {
+  return (
+    <div data-slot="calendar" ref={rootRef} className={className} {...props} />
+  );
+}
+
+function CalendarChevron({
+  className,
+  orientation,
+}: React.ComponentProps<typeof Chevron>) {
+  const iconClass = cn("size-4", className);
+  if (orientation === "left") return <IconChevronLeft className={iconClass} />;
+  if (orientation === "right") {
+    return <IconChevronRight className={iconClass} />;
+  }
+  return <IconChevronDown className={iconClass} />;
+}
+
+function Calendar({
+  className,
+  classNames,
+  showOutsideDays = true,
+  captionLayout = "label",
+  formatters,
+  components,
+  ...props
+}: React.ComponentProps<typeof DayPicker>) {
+  const defaultClassNames = getDefaultClassNames();
+
+  return (
+    <DayPicker
+      showOutsideDays={showOutsideDays}
+      className={cn(
+        "group/calendar p-1 text-foreground [--cell-size:--spacing(8)]",
+        String.raw`rtl:**:[.rdp-button\_next>svg]:rotate-180`,
+        String.raw`rtl:**:[.rdp-button\_previous>svg]:rotate-180`,
+        className,
+      )}
+      captionLayout={captionLayout}
+      formatters={{
+        formatMonthDropdown: (date) =>
+          date.toLocaleString("default", { month: "short" }),
+        ...formatters,
+      }}
+      classNames={{
+        root: cn("w-fit", defaultClassNames.root),
+        months: cn(
+          "relative flex flex-col gap-4 md:flex-row",
+          defaultClassNames.months,
+        ),
+        month: cn("flex w-full flex-col gap-2", defaultClassNames.month),
+        nav: cn(
+          "absolute inset-x-0 top-0 flex w-full items-center justify-between gap-1",
+          defaultClassNames.nav,
+        ),
+        button_previous: cn(navButtonClass, defaultClassNames.button_previous),
+        button_next: cn(navButtonClass, defaultClassNames.button_next),
+        month_caption: cn(
+          "flex h-(--cell-size) w-full items-center justify-center px-(--cell-size)",
+          defaultClassNames.month_caption,
+        ),
+        dropdowns: cn(
+          "flex h-(--cell-size) w-full items-center justify-center gap-1.5 text-xs font-medium",
+          defaultClassNames.dropdowns,
+        ),
+        dropdown_root: cn(
+          "relative rounded-field border border-border has-focus:border-focus-border has-focus:ring-2 has-focus:ring-focus-ring",
+          defaultClassNames.dropdown_root,
+        ),
+        dropdown: cn(
+          "absolute inset-0 bg-overlay opacity-0",
+          defaultClassNames.dropdown,
+        ),
+        caption_label: cn(
+          "select-none text-xs font-medium",
+          captionLayout !== "label" &&
+            "flex h-7 items-center gap-1 rounded-field pl-2 pr-1 [&>svg]:size-3.5 [&>svg]:text-muted-foreground",
+          defaultClassNames.caption_label,
+        ),
+        month_grid: "w-full border-collapse",
+        weekdays: cn("flex", defaultClassNames.weekdays),
+        weekday: cn(
+          "flex-1 select-none text-[10px] font-normal uppercase tracking-wider text-muted-foreground",
+          defaultClassNames.weekday,
+        ),
+        week: cn("mt-1 flex w-full", defaultClassNames.week),
+        week_number_header: cn(
+          "w-(--cell-size) select-none",
+          defaultClassNames.week_number_header,
+        ),
+        week_number: cn(
+          "select-none text-[10px] text-muted-foreground",
+          defaultClassNames.week_number,
+        ),
+        day: cn(
+          "group/day relative aspect-square h-full w-full select-none p-0 text-center",
+          defaultClassNames.day,
+        ),
+        day_button: cn(
+          "relative inline-flex size-(--cell-size) items-center justify-center rounded-lg text-xs tabular-nums text-foreground/80 transition-colors disabled:cursor-not-allowed disabled:opacity-40",
+          pickerFocusClass,
+          // today, outside and hover rules exclude selected days, so the
+          // selected tone never depends on the order Tailwind emits rules in.
+          // the today dot is `bg-current`: foreground, or primary-foreground
+          // when selected
+          "not-group-data-selected/day:enabled:hover:bg-surface-tertiary/50",
+          "group-data-today/day:font-semibold group-data-today/day:not-group-data-selected/day:text-foreground group-data-today/day:after:absolute group-data-today/day:after:bottom-1 group-data-today/day:after:left-1/2 group-data-today/day:after:size-1 group-data-today/day:after:-translate-x-1/2 group-data-today/day:after:rounded-full group-data-today/day:after:bg-current",
+          "group-data-outside/day:not-group-data-selected/day:text-muted-foreground",
+          // spelled out (not built from pickerSelectedClass) so Tailwind's
+          // scanner sees it
+          "group-data-selected/day:bg-primary group-data-selected/day:text-primary-foreground",
+          defaultClassNames.day_button,
+        ),
+        range_start: cn("rounded-l-lg", defaultClassNames.range_start),
+        range_middle: cn("rounded-none", defaultClassNames.range_middle),
+        range_end: cn("rounded-r-lg", defaultClassNames.range_end),
+        hidden: cn("invisible", defaultClassNames.hidden),
+        ...classNames,
+      }}
+      components={{
+        Root: CalendarRoot,
+        Chevron: CalendarChevron,
+        ...components,
+      }}
+      {...props}
+    />
+  );
+}
+
+export { Calendar };

package/src/ui/date-picker.tsx

@@ -0,0 +1,545 @@
+import * as React from "react";
+import {
+  IconCalendar,
+  IconCalendarMonth,
+  IconChevronLeft,
+  IconChevronRight,
+  IconX,
+} from "@tabler/icons-react";
+import type { Matcher } from "react-day-picker";
+import { cn } from "../utils/cn";
+import { assignRef } from "../utils/ref";
+import {
+  pickerFocusClass,
+  pickerFieldClass,
+  pickerItemHoverClass,
+  pickerSelectedClass,
+  pickerTriggerClass,
+} from "./_picker-classes";
+import { Calendar } from "./calendar";
+import { Popover, PopoverContent, PopoverTrigger } from "./popover";
+import { TimePicker } from "./time-picker";
+
+// controlled replacements for `<input type="date">`, `"datetime-local"` and
+// `"month">`: the values are the native strings ("YYYY-MM-DD",
+// "YYYY-MM-DDTHH:mm", "YYYY-MM", "" when empty), read and written as local
+// calendar dates. there is no timezone logic; like TimePicker, the consumer
+// owns any local↔utc conversion
+
+const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const MONTH_RE = /^(\d{4})-(\d{2})$/;
+const DATE_TIME_RE = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})$/;
+
+const pad = (n: number, width = 2) => String(n).padStart(width, "0");
+
+// "YYYY-MM-DD" -> local midnight, or undefined for "" and invalid dates
+// (2025-02-30). never `new Date("YYYY-MM-DD")`, which parses as utc midnight
+// and lands on the previous day west of greenwich
+function parseDateValue(value: string): Date | undefined {
+  const match = DATE_RE.exec(value);
+  if (!match) return undefined;
+  const year = Number(match[1]);
+  const month = Number(match[2]) - 1;
+  const day = Number(match[3]);
+  // setFullYear keeps years 0-99 literal (the Date constructor maps them to 19xx)
+  const date = new Date(2000, 0, 1);
+  date.setFullYear(year, month, day);
+  if (
+    date.getFullYear() !== year ||
+    date.getMonth() !== month ||
+    date.getDate() !== day
+  ) {
+    return undefined;
+  }
+  return date;
+}
+
+// local calendar date -> "YYYY-MM-DD" ("" for an invalid date)
+function formatDateValue(date: Date): string {
+  if (Number.isNaN(date.getTime())) return "";
+  return `${pad(date.getFullYear(), 4)}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+function parseMonthValue(
+  value: string,
+): { year: number; month: number } | undefined {
+  const match = MONTH_RE.exec(value);
+  if (!match) return undefined;
+  const year = Number(match[1]);
+  const month = Number(match[2]) - 1;
+  if (month < 0 || month > 11) return undefined;
+  return { year, month };
+}
+
+const formatMonthValue = (year: number, month: number) =>
+  `${pad(year, 4)}-${pad(month + 1)}`;
+
+function localDate(year: number, month: number): Date {
+  const date = new Date(2000, 0, 1);
+  date.setFullYear(year, month, 1);
+  return date;
+}
+
+// wrapper, input-styled trigger, optional clear control and hidden input
+// shared by DatePicker and MonthPicker. the clear control is a sibling of the
+// trigger (buttons cannot nest), overlaid inside the field on the right, and
+// hands focus back to the trigger. the trigger grows with the wrapper, so a
+// width on either `className` or `triggerClassName` sizes the field
+interface PickerFieldProps {
+  triggerRef: React.Ref<HTMLButtonElement>;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  value: string;
+  text: string | undefined;
+  placeholder: string;
+  icon: React.ReactNode;
+  clearLabel: string;
+  onClear: () => void;
+  clearable?: boolean;
+  disabled?: boolean;
+  ariaLabel?: string;
+  className?: string;
+  triggerClassName?: string;
+  id?: string;
+  name?: string;
+  children: React.ReactNode;
+}
+
+function PickerField({
+  triggerRef,
+  open,
+  onOpenChange,
+  value,
+  text,
+  placeholder,
+  icon,
+  clearLabel,
+  onClear,
+  clearable,
+  disabled,
+  ariaLabel,
+  className,
+  triggerClassName,
+  id,
+  name,
+  children,
+}: PickerFieldProps) {
+  const buttonRef = React.useRef<HTMLButtonElement | null>(null);
+  const showClear = clearable && text !== undefined && !disabled;
+
+  return (
+    <div className={cn(pickerFieldClass, className)}>
+      <Popover open={open} onOpenChange={onOpenChange}>
+        <PopoverTrigger asChild>
+          <button
+            ref={(node) => {
+              buttonRef.current = node;
+              assignRef(triggerRef, node);
+            }}
+            id={id}
+            type="button"
+            disabled={disabled}
+            aria-label={
+              ariaLabel ? `${ariaLabel}, ${text ?? placeholder}` : undefined
+            }
+            className={cn(pickerTriggerClass, "w-40 min-w-0 grow", triggerClassName)}
+          >
+            <span
+              className={cn(
+                "truncate",
+                text === undefined && "text-field-placeholder",
+                showClear && "pr-7",
+              )}
+            >
+              {text ?? placeholder}
+            </span>
+            {icon}
+          </button>
+        </PopoverTrigger>
+        <PopoverContent align="start" sideOffset={4} className="w-auto p-2">
+          {children}
+        </PopoverContent>
+      </Popover>
+      {showClear ? (
+        <button
+          type="button"
+          aria-label={clearLabel}
+          onClick={() => {
+            onClear();
+            buttonRef.current?.focus();
+          }}
+          className={cn(
+            "absolute right-8 top-1/2 inline-flex size-5 -translate-y-1/2 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-surface-tertiary hover:text-foreground",
+            pickerFocusClass,
+          )}
+        >
+          <IconX className="size-3" />
+        </button>
+      ) : null}
+      {name ? <input type="hidden" name={name} value={value} /> : null}
+    </div>
+  );
+}
+
+interface DatePickerProps {
+  // "YYYY-MM-DD" or "" (what `<input type="date">` uses)
+  value: string;
+  onChange: (value: string) => void;
+  // "YYYY-MM-DD"; days outside the range are disabled
+  min?: string;
+  max?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  // names the trigger; the shown date or placeholder is appended
+  ariaLabel?: string;
+  // the wrapper (trigger plus clear control)
+  className?: string;
+  // merged onto the trigger (default width `w-40`); `w-full`, height, radius,
+  // padding and text size override cleanly
+  triggerClassName?: string;
+  // shows a clear control that calls `onChange("")`
+  clearable?: boolean;
+  // BCP 47 locale for the trigger text (default: the runtime's)
+  locale?: string;
+  id?: string;
+  // renders a hidden input with `value` so forms still submit it
+  name?: string;
+}
+
+const DatePicker = React.forwardRef<HTMLButtonElement, DatePickerProps>(
+  (
+    {
+      value,
+      onChange,
+      min,
+      max,
+      placeholder = "Pick a date",
+      disabled,
+      ariaLabel,
+      className,
+      triggerClassName,
+      clearable,
+      locale,
+      id,
+      name,
+    },
+    ref,
+  ) => {
+    const [open, setOpen] = React.useState(false);
+    const selected = parseDateValue(value);
+    const minDate = min ? parseDateValue(min) : undefined;
+    const maxDate = max ? parseDateValue(max) : undefined;
+    const outOfRange: Matcher[] = [
+      ...(minDate ? [{ before: minDate }] : []),
+      ...(maxDate ? [{ after: maxDate }] : []),
+    ];
+
+    return (
+      <PickerField
+        triggerRef={ref}
+        open={open}
+        onOpenChange={setOpen}
+        value={value}
+        text={
+          selected
+            ? new Intl.DateTimeFormat(locale, { dateStyle: "medium" }).format(
+                selected,
+              )
+            : undefined
+        }
+        placeholder={placeholder}
+        icon={<IconCalendar className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />}
+        clearLabel="Clear date"
+        onClear={() => onChange("")}
+        clearable={clearable}
+        disabled={disabled}
+        ariaLabel={ariaLabel}
+        className={className}
+        triggerClassName={triggerClassName}
+        id={id}
+        name={name}
+      >
+        <Calendar
+          mode="single"
+          required
+          selected={selected}
+          defaultMonth={selected ?? minDate}
+          startMonth={minDate}
+          endMonth={maxDate}
+          disabled={outOfRange}
+          autoFocus
+          onSelect={(date) => {
+            onChange(formatDateValue(date));
+            setOpen(false);
+          }}
+        />
+      </PickerField>
+    );
+  },
+);
+DatePicker.displayName = "DatePicker";
+
+interface DateTimePickerProps {
+  // "YYYY-MM-DDTHH:mm" or "" (what `<input type="datetime-local">` uses)
+  value: string;
+  onChange: (value: string) => void;
+  // "YYYY-MM-DDTHH:mm"; only the date part limits the calendar
+  min?: string;
+  max?: string;
+  // time used when a date is picked before any time (default "00:00")
+  defaultTime?: string;
+  disabled?: boolean;
+  // names both triggers ("<label>, date" and "<label>, time")
+  ariaLabel?: string;
+  // the row; a width here (`w-full`) grows the date field, the time keeps 110px
+  className?: string;
+  // merged onto both triggers (height, radius, padding, text size); a width
+  // applies to the date trigger only, the time keeps 110px
+  triggerClassName?: string;
+  // on the date trigger
+  id?: string;
+  // renders a hidden input with the combined value
+  name?: string;
+  locale?: string;
+}
+
+function splitDateTime(value: string): { date: string; time: string } {
+  const match = DATE_TIME_RE.exec(value);
+  if (!match) return { date: "", time: "" };
+  return { date: match[1] ?? "", time: match[2] ?? "" };
+}
+
+const DateTimePicker = React.forwardRef<HTMLButtonElement, DateTimePickerProps>(
+  (
+    {
+      value,
+      onChange,
+      min,
+      max,
+      defaultTime = "00:00",
+      disabled,
+      ariaLabel,
+      className,
+      triggerClassName,
+      id,
+      name,
+      locale,
+    },
+    ref,
+  ) => {
+    const { date, time } = splitDateTime(value);
+
+    return (
+      <div className={cn(pickerFieldClass, "items-center gap-2", className)}>
+        <DatePicker
+          className="min-w-0 grow"
+          triggerClassName={triggerClassName}
+          ref={ref}
+          id={id}
+          value={date}
+          onChange={(next) => onChange(next ? `${next}T${time || defaultTime}` : "")}
+          min={min?.slice(0, 10)}
+          max={max?.slice(0, 10)}
+          disabled={disabled}
+          ariaLabel={ariaLabel ? `${ariaLabel}, date` : "Date"}
+          locale={locale}
+        />
+        <TimePicker
+          value={time || defaultTime}
+          onChange={(next) =>
+            onChange(`${date || formatDateValue(new Date())}T${next}`)
+          }
+          disabled={disabled}
+          ariaLabel={ariaLabel ? `${ariaLabel}, time` : "Time"}
+          className="shrink-0"
+          triggerClassName={cn(triggerClassName, "w-[110px]")}
+        />
+        {name ? <input type="hidden" name={name} value={value} /> : null}
+      </div>
+    );
+  },
+);
+DateTimePicker.displayName = "DateTimePicker";
+
+interface MonthPickerProps {
+  // "YYYY-MM" or "" (what `<input type="month">` uses)
+  value: string;
+  onChange: (value: string) => void;
+  // "YYYY-MM"; months outside the range are disabled
+  min?: string;
+  max?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  ariaLabel?: string;
+  className?: string;
+  // merged onto the trigger, as on DatePicker
+  triggerClassName?: string;
+  clearable?: boolean;
+  locale?: string;
+  id?: string;
+  name?: string;
+}
+
+const MonthPicker = React.forwardRef<HTMLButtonElement, MonthPickerProps>(
+  (
+    {
+      value,
+      onChange,
+      min,
+      max,
+      placeholder = "Pick a month",
+      disabled,
+      ariaLabel,
+      className,
+      triggerClassName,
+      clearable,
+      locale,
+      id,
+      name,
+    },
+    ref,
+  ) => {
+    const [open, setOpen] = React.useState(false);
+    const selected = parseMonthValue(value);
+
+    return (
+      <PickerField
+        triggerRef={ref}
+        open={open}
+        onOpenChange={setOpen}
+        value={value}
+        text={
+          selected
+            ? new Intl.DateTimeFormat(locale, {
+                month: "short",
+                year: "numeric",
+              }).format(localDate(selected.year, selected.month))
+            : undefined
+        }
+        placeholder={placeholder}
+        icon={
+          <IconCalendarMonth className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+        }
+        clearLabel="Clear month"
+        onClear={() => onChange("")}
+        clearable={clearable}
+        disabled={disabled}
+        ariaLabel={ariaLabel}
+        className={className}
+        triggerClassName={triggerClassName}
+        id={id}
+        name={name}
+      >
+        <MonthGrid
+          value={value}
+          min={min}
+          max={max}
+          locale={locale}
+          onSelect={(next) => {
+            onChange(next);
+            setOpen(false);
+          }}
+        />
+      </PickerField>
+    );
+  },
+);
+MonthPicker.displayName = "MonthPicker";
+
+interface MonthGridProps {
+  value: string;
+  min?: string;
+  max?: string;
+  locale?: string;
+  onSelect: (value: string) => void;
+}
+
+// mounted only while the popover is open, so the shown year starts at the
+// selected one (else the current year, kept inside min/max) on every open
+function MonthGrid({ value, min, max, locale, onSelect }: MonthGridProps) {
+  const minYear = parseMonthValue(min ?? "")?.year;
+  const maxYear = parseMonthValue(max ?? "")?.year;
+  const [year, setYear] = React.useState(() => {
+    const initial =
+      parseMonthValue(value)?.year ?? new Date().getFullYear();
+    if (maxYear !== undefined && initial > maxYear) return maxYear;
+    if (minYear !== undefined && initial < minYear) return minYear;
+    return initial;
+  });
+  const short = new Intl.DateTimeFormat(locale, { month: "short" });
+  const long = new Intl.DateTimeFormat(locale, {
+    month: "long",
+    year: "numeric",
+  });
+  const navClass = cn(
+    "inline-flex size-8 items-center justify-center rounded-lg text-muted-foreground transition-colors hover:bg-surface-tertiary hover:text-foreground disabled:pointer-events-none disabled:opacity-50",
+    pickerFocusClass,
+  );
+
+  return (
+    <div className="flex w-56 flex-col gap-2 p-1">
+      <div className="flex items-center justify-between">
+        <button
+          type="button"
+          aria-label="Previous year"
+          disabled={minYear !== undefined && year <= minYear}
+          onClick={() => setYear(year - 1)}
+          className={navClass}
+        >
+          <IconChevronLeft className="size-4" />
+        </button>
+        <div aria-live="polite" className="text-xs font-medium tabular-nums">
+          {year}
+        </div>
+        <button
+          type="button"
+          aria-label="Next year"
+          disabled={maxYear !== undefined && year >= maxYear}
+          onClick={() => setYear(year + 1)}
+          className={navClass}
+        >
+          <IconChevronRight className="size-4" />
+        </button>
+      </div>
+      <div role="group" aria-label={String(year)} className="grid grid-cols-3 gap-1">
+        {Array.from({ length: 12 }, (_, month) => {
+          const monthValue = formatMonthValue(year, month);
+          const date = localDate(year, month);
+          const isSelected = monthValue === value;
+          // "YYYY-MM" strings compare in calendar order
+          const outOfRange =
+            (!!min && monthValue < min) || (!!max && monthValue > max);
+          return (
+            <button
+              key={month}
+              type="button"
+              aria-label={long.format(date)}
+              aria-pressed={isSelected}
+              disabled={outOfRange}
+              data-month-value={monthValue}
+              onClick={() => onSelect(monthValue)}
+              className={cn(
+                "flex h-8 items-center justify-center rounded-lg text-xs transition-colors disabled:cursor-not-allowed disabled:opacity-40",
+                pickerFocusClass,
+                isSelected
+                  ? pickerSelectedClass
+                  : cn("text-foreground/80", pickerItemHoverClass),
+              )}
+            >
+              {short.format(date)}
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+export {
+  DatePicker,
+  DateTimePicker,
+  MonthPicker,
+  parseDateValue,
+  formatDateValue,
+};
+export type { DatePickerProps, DateTimePickerProps, MonthPickerProps };

package/src/ui/dialog.tsx

@@ -211,6 +211,10 @@ const DialogBody = ({
 );
 DialogBody.displayName = "DialogBody";
 
+// no fill of its own: the footer is not sticky, so it shows the content's
+// surface. a token here (it was `bg-overlay`) showed as an inset block when
+// that surface differs (`glass-panel-strong` from the app, or `bg-*` on the
+// content)
 const DialogFooter = ({
   className,
   ...props
@@ -218,7 +222,7 @@ const DialogFooter = ({
   <div
     data-slot="dialog-footer"
     className={cn(
-      "mt-auto flex flex-col-reverse gap-2 bg-overlay pt-2 sm:flex-row sm:justify-end",
+      "mt-auto flex flex-col-reverse gap-2 pt-2 sm:flex-row sm:justify-end",
       "pb-[max(0px,env(safe-area-inset-bottom,0px))]",
       "[&_button]:max-sm:min-h-11",
       className,

package/src/ui/time-picker.tsx

@@ -2,6 +2,11 @@ import * as React from "react";
 import { IconClock } from "@tabler/icons-react";
 import { Popover, PopoverContent, PopoverTrigger } from "./popover";
 import { cn } from "../utils/cn";
+import {
+  pickerItemHoverClass,
+  pickerSelectedClass,
+  pickerTriggerClass,
+} from "./_picker-classes";
 
 // custom 24, hour "hh:mm" time picker replaces `<input type="time">` because the native picker varies wildly
 // across browsers and platforms (chrome/firefox/safari each render a
@@ -15,7 +20,8 @@ interface TimePickerProps {
   className?: string;
   disabled?: boolean;
   ariaLabel?: string;
-  // width of the trigger button defaults to a compact 110px
+  // merged onto the trigger (width defaults to a compact 110px; height,
+  // radius, padding and text size override cleanly)
   triggerClassName?: string;
 }
 
@@ -88,8 +94,9 @@ const TimePicker = React.forwardRef<HTMLButtonElement, TimePickerProps>(
             disabled={disabled}
             aria-label={ariaLabel}
             className={cn(
-              "inline-flex h-8 items-center justify-between gap-2 rounded-field border border-border bg-field-background px-2.5 text-xs font-medium tabular-nums transition-[border-color,box-shadow,background-color] duration-200 ease-smooth hover:bg-field-background/90 focus-visible:border-focus-border focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring disabled:cursor-not-allowed disabled:opacity-50",
-              triggerClassName ?? "w-[110px]",
+              pickerTriggerClass,
+              "w-[110px]",
+              triggerClassName,
               className,
             )}
           >
@@ -152,8 +159,8 @@ const TimeColumn = React.forwardRef<HTMLDivElement, TimeColumnProps>(
                 className={cn(
                   "flex h-7 w-full items-center justify-center text-xs tabular-nums transition-colors",
                   isSelected
-                    ? "bg-primary text-primary-foreground"
-                    : "text-foreground/80 hover:bg-surface-tertiary/50",
+                    ? pickerSelectedClass
+                    : cn("text-foreground/80", pickerItemHoverClass),
                 )}
               >
                 {v}