cupertino-datetime-picker 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Klaus Fan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# cupertino-datetime-picker
+
+**[Documentation](https://cupertino-datetime-picker-docs.vercel.app)** ·
+**[Installation](https://cupertino-datetime-picker-docs.vercel.app/docs/installation)** ·
+**[npm](https://www.npmjs.com/package/cupertino-datetime-picker)**
+
+The iOS 14+ compact date & time picker, for the web. A date pill and a time
+pill; the date pill opens the inline calendar whose title turns into month and
+year wheels, the time pill opens hour / minute / AM–PM wheels with a typed
+field above them. Every part takes touch, mouse, trackpad and keyboard.
+
+Built for [shadcn/ui](https://ui.shadcn.com) on
+[Base UI](https://base-ui.com) popovers and Tailwind v4. No date library:
+`Intl` supplies month names, weekday names, the 12/24-hour clock and the
+first day of the week.
+
+## Install
+
+As a shadcn registry item (the source lands in your project, under
+`components/ui/cupertino/`):
+
+```sh
+npx shadcn@latest add https://cupertino-datetime-picker-docs.vercel.app/r/cupertino-datetime-picker.json
+```
+
+Or from npm:
+
+```sh
+pnpm add cupertino-datetime-picker @base-ui/react
+```
+
+```css
+/* your Tailwind entry */
+@import "tailwindcss";
+@import "cupertino-datetime-picker/styles.css";
+@source "../node_modules/cupertino-datetime-picker/dist";
+```
+
+## Use
+
+```tsx
+import { DateTimePicker } from "cupertino-datetime-picker";
+
+<DateTimePicker value={date} onChange={setDate} />
+<DateTimePicker mode="date" />
+<DateTimePicker mode="time" minuteInterval={5} />
+<DateTimePicker display="inline" locale="de-DE" />
+```
+
+| Prop                                  | Default              |                                                        |
+| ------------------------------------- | -------------------- | ------------------------------------------------------ |
+| `value` / `defaultValue` / `onChange` |                      | `Date \| null`. Controlled when `value` is given.      |
+| `mode`                                | `"dateTime"`         | `"date"`, `"time"`, or both — `UIDatePicker.Mode`.     |
+| `display`                             | `"compact"`          | `"compact"` pills with popovers, or `"inline"` panels. |
+| `locale`                              | `navigator.language` | Drives names, clock, week start and the pill formats.  |
+| `hourCycle`                           | from locale          | `"h12"` or `"h23"`.                                    |
+| `minuteInterval`                      | `1`                  | Minute wheel step, like `UIDatePicker.minuteInterval`. |
+| `min` / `max`                         |                      | Days outside the range are disabled.                   |
+
+The panels are exported on their own (`CalendarPanel`, `TimePanel`) as are
+the primitives (`Wheel`, `WheelHighlight`, `SegmentedControl`).
+
+Re-tint with `--cdp-tint` (and `--cdp-on-tint` for text on it); dark mode
+follows a `.dark` (or `data-theme="dark"`) ancestor. Accessible names are
+English by default; pass `labels` to `CalendarPanel` / `TimePanel` to
+translate them — the visible text is already the locale's.
+
+## What matches iOS
+
+- Pills: 34pt, 8pt radius, tertiary fill, tint text while open.
+- Calendar: "September 2026 ›" title, next/previous in tint, single-letter
+  weekdays, 20pt days in 40pt circles. Selected day is a tinted circle; today
+  is tint text; selected today is a filled tint circle. Only the rows the
+  month needs. Months slide in; the title cross-fades the grid into month and
+  year wheels. Horizontal swipe changes month.
+- Wheels: native scroll with snap points, so touch and trackpad flings are
+  the platform's own. Mouse drag has its own deceleration. Rows tilt away
+  from the centre and fade at the edges; hour and minute wheels wrap.
+- Time field: hour and minute segments. Digits auto-advance (`945` is 9:45,
+  `12` waits for the second digit, `13` becomes 3), arrows step, `a`/`p` set
+  the period, and the wheels spin to follow. Spin a wheel and the digits
+  follow back. Mobile keypads insert through `beforeinput`, so IMEs work.
+- Segmented control for AM/PM with the sliding thumb.
+- Popover springs in from its pill.
+
+## Keyboard
+
+| Where         | Keys                                                                                              |
+| ------------- | ------------------------------------------------------------------------------------------------- |
+| Calendar grid | ← → ↑ ↓ move a day / week, Home/End week bounds, PageUp/PageDown month (Shift: year), Enter picks |
+| Any wheel     | ↑ ↓ one row, PageUp/PageDown five, Home/End, type a value to jump                                 |
+| Time field    | digits, ↑ ↓ step, ← → between segments, `a` / `p`, Backspace clears                               |
+| Popover       | Escape closes                                                                                     |
+
+All wheels are `spinbutton`s with `aria-valuenow` / `aria-valuetext`; the
+grid is a `grid` of `gridcell`s with full-date names.
+
+## Develop
+
+```sh
+pnpm install
+pnpm dev          # demo at http://localhost:5173
+pnpm test         # vitest: calendar math, clock, segment typing, fling math
+pnpm e2e          # Playwright: desktop Chrome + iPhone 15 (touch flings via CDP)
+pnpm check        # typecheck, lint, tests, build
+pnpm registry:build   # shadcn registry JSON into docs/public/r
+pnpm docs         # documentation site (Fumadocs) at http://localhost:3000
+```
+
+## Not yet
+
+- RTL locales.
+- `wheels` display for the date (day / month / year drums).
+- Ranges.

package/dist/calendar-panel.d.ts

@@ -0,0 +1,27 @@
+import * as React from "react";
+export type CalendarPanelLabels = {
+    previousMonth: string;
+    nextMonth: string;
+    month: string;
+    year: string;
+};
+export declare const CALENDAR_LABELS: CalendarPanelLabels;
+export type CalendarPanelProps = {
+    value: Date | null;
+    onChange: (date: Date) => void;
+    locale?: string;
+    min?: Date;
+    max?: Date;
+    /** Accessible names; visible text comes from `Intl`. */
+    labels?: Partial<CalendarPanelLabels>;
+    /** Injected for tests and stories. */
+    today?: Date;
+    className?: string;
+};
+/**
+ * The iOS inline calendar: month title that opens month/year wheels, next
+ * and previous month, a grid of circles. Months slide, the wheels cross-fade
+ * in over the grid, a horizontal swipe changes month, and the keyboard walks
+ * the grid (arrows, Home/End, PageUp/PageDown, Enter).
+ */
+export declare function CalendarPanel({ value, onChange, locale, min, max, labels: labelsProp, today: todayProp, className, }: CalendarPanelProps): React.JSX.Element;

package/dist/calendar.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Calendar arithmetic on local `Date`s, with no library. A picker only ever
+ * needs the month grid, day-level comparisons, and "same clock, other day".
+ */
+export type YearMonth = {
+    year: number;
+    month: number;
+};
+export declare function startOfDay(date: Date): Date;
+export declare function isSameDay(a: Date | null | undefined, b: Date | null | undefined): boolean;
+export declare function daysInMonth(year: number, month: number): number;
+export declare function yearMonthOf(date: Date): YearMonth;
+/** Months between `a` and `b`; negative when `b` is earlier. */
+export declare function monthDiff(a: YearMonth, b: YearMonth): number;
+export declare function shiftMonth(ym: YearMonth, by: number): YearMonth;
+/** The same clock on another calendar day; the day is clamped into the month. */
+export declare function withDay(base: Date, year: number, month: number, day: number): Date;
+export declare function withTime(base: Date, hours: number, minutes: number): Date;
+export declare function addDays(date: Date, days: number): Date;
+export declare function addMonths(date: Date, months: number): Date;
+/** Whether the whole day lies outside [min, max]. */
+export declare function isDayDisabled(date: Date, min?: Date, max?: Date): boolean;
+export type DayCell = {
+    date: Date;
+    inMonth: boolean;
+};
+/**
+ * Rows of seven for one month, starting on `weekStart` (0 = Sunday). Only as
+ * many rows as the month needs, like the iOS inline calendar.
+ */
+export declare function monthGrid(year: number, month: number, weekStart: number): DayCell[][];
+/** First day of the week for a locale, 0 = Sunday … 6 = Saturday. */
+export declare function weekStartFor(locale: string): number;

package/dist/date-time-picker.d.ts

@@ -0,0 +1,31 @@
+import { HourCycle } from './time';
+export type DateTimePickerProps = {
+    value?: Date | null;
+    defaultValue?: Date | null;
+    onChange?: (date: Date | null) => void;
+    /** Which parts are editable — `UIDatePicker.Mode`. */
+    mode?: "date" | "time" | "dateTime";
+    /** Pills that open popovers (`.compact`), or the panels laid out in place (`.inline`). */
+    display?: "compact" | "inline";
+    locale?: string;
+    hourCycle?: HourCycle;
+    minuteInterval?: number;
+    min?: Date;
+    max?: Date;
+    disabled?: boolean;
+    className?: string;
+    /** Placeholder labels when there is no value. */
+    labels?: {
+        date?: string;
+        time?: string;
+    };
+};
+/** The compact pill and its popover, for composing your own rows. */
+export declare const pillClass = "inline-flex h-[34px] items-center rounded-lg bg-[var(--cdp-fill)] px-3 text-[17px] leading-none text-[var(--cdp-label)] transition-[background-color,color] outline-none hover:bg-[var(--cdp-fill-hover)] focus-visible:ring-2 focus-visible:ring-[var(--cdp-tint)] active:opacity-60 disabled:opacity-40 data-popup-open:text-[var(--cdp-tint)]";
+export declare const popupClass = "cdp origin-(--transform-origin) rounded-[13px] bg-[var(--cdp-bg)] shadow-[var(--cdp-shadow)] outline-none data-open:animate-[cdp-pop-in_260ms_cubic-bezier(0.18,0.9,0.32,1.15)] data-closed:animate-[cdp-pop-out_140ms_ease-in]";
+/**
+ * The iOS 14+ date picker for the web. Compact display shows the date and
+ * time as pills; each opens a popover — the calendar or the time panel —
+ * anchored to it. Inline display lays the panels out in place.
+ */
+export declare function DateTimePicker({ value: valueProp, defaultValue, onChange, mode, display, locale, hourCycle: hourCycleProp, minuteInterval, min, max, disabled, className, labels, }: DateTimePickerProps): import("react").JSX.Element;

package/dist/hooks.d.ts

@@ -0,0 +1,3 @@
+/** Controlled when `value` is given, otherwise owned here. */
+export declare function useControlled<T>(value: T | undefined, defaultValue: T, onChange: ((next: T) => void) | undefined): [T, (next: T) => void];
+export declare function usePrefersReducedMotion(): boolean;

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { DateTimePicker, pillClass, popupClass, type DateTimePickerProps, } from './date-time-picker';
+export { CalendarPanel, CALENDAR_LABELS, type CalendarPanelLabels, type CalendarPanelProps, } from './calendar-panel';
+export { TimePanel, TIME_LABELS, type TimePanelLabels, type TimePanelProps } from './time-panel';
+export { Wheel, WheelHighlight, type WheelOption, type WheelProps } from './wheel';
+export { SegmentedControl, type SegmentedOption } from './segmented-control';
+export * from './calendar';
+export * from './time';
+export { typeDigit, stepValue, type DigitStep } from './segments';