@gridui/date-picker 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# @gridui/date-picker
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Single-date selection, inclusive date ranges and an independent embedded date panel. This family does not depend on the scheduling Calendar or Grid.
+
+```tsx
+import "@gridui/theme/styles.css";
+import "@gridui/button/styles.css";
+import "@gridui/overlay/styles.css";
+import "@gridui/popover/styles.css";
+import "@gridui/date-picker/styles.css";
+
+import { DatePicker, DateRangePicker, DatePickerPanel } from "@gridui/date-picker";
+
+<DatePicker
+    label="Event date"
+    defaultMonth="2026-11-01"
+    defaultValue="2026-11-05"
+    name="eventDate"
+/>;
+
+<DateRangePicker
+    label="Event dates"
+    defaultMonth="2026-11-01"
+    value={range}
+    onValueChange={setRange}
+/>;
+
+<DatePickerPanel
+    defaultMonth="2026-11-01"
+    value={date}
+    onValueChange={setDate}
+/>;
+```
+
+## Selection and composition
+
+`DatePickerPanel` is a standalone native date grid, with `mode="single"` (default) or `mode="range"`. It has no popover, application heading, form submission or persistence. Use it inside a GridItem, Popover, Drawer or custom form. It never requires another DatePicker component or provider. In range mode it reports the draft after each selection; applications can commit immediately or supply their own confirmation flow.
+
+`DatePicker` and `DateRangePicker` compose that panel with GridUI Popover and Button. A single date commits and closes on selection. A range has separate draft state and commits only with Apply. Cancel, Escape and outside dismissal discard the draft when reopened. Clearing commits `null` immediately. Optional `footer` content belongs to the application; it can provide preset actions through controlled values or the standalone panel. Popover owns focus restoration, Escape and outside dismissal.
+
+Use `value`/`onValueChange` for controlled state, or `defaultValue` for local state. Explicit `null` means empty. `open`/`onOpenChange` and `defaultOpen` provide the same choice for popups. Read-only and disabled pickers do not open or change values. Controlled consumers may reject changes. Native div props and refs reach the component root.
+
+## Dates, bounds and localization
+
+`DateValue` is a Gregorian `YYYY-MM-DD` civil date, not an instant. The package does not infer a timezone or read the current clock during rendering. `defaultMonth` is required for deterministic SSR; supply `today` for the current-day marker and Today action. Values are validated instead of accepting JavaScript's invalid-day rollover.
+
+`DateRange` has `start` and optional `end`. Both ends are **inclusive**; a missing end is an incomplete draft. Choosing an earlier endpoint sorts the range. A completed range starts over on the next selection.
+
+`min`, `max` and `isDateDisabled` govern selection. Bounds are inclusive and ordered. A range cannot contain a disabled day: an attempted blocked interval starts a new draft at the clicked date. Existing controlled values are displayed even when later constraints make them unavailable; applications own validation of previously stored data. `isDateDisabled` must be a pure, inexpensive predicate.
+
+`month`/`onMonthChange` optionally control the visible month; month values normalize to the first day. `months` accepts 1 or 2. Two months sit side by side when the panel has enough space and stack in narrow containers. `weekStartsOn` accepts 0–6 and defaults to Monday. `locale` defaults to `en-US`; date formatting uses an explicit UTC projection of civil dates so server/browser timezones cannot change the caption.
+
+Localize navigation with `labels`, popup actions with `pickerLabels`, and displayed field values with `formatValue`. `label` is required on popup pickers. `size="standard" | "small"` selects date-cell/control density. Coarse pointers retain the standard cell height.
+
+## Keyboard and forms
+
+The day grid has one tab stop across both visible months. Arrow keys move by day/week, Home/End by the configured week, PageUp/PageDown by month, and Shift+PageUp/PageDown by year. Horizontal movement follows writing direction. Enter/Space selects. Unavailable dates remain discoverable with `aria-disabled` but cannot be selected. Native focus indicators stay inside the date cell. Month navigation remains separate native buttons.
+
+`name` adds a hidden form entry for a single date. Ranges use `${name}.start` and `${name}.end`. `form` supports external form ownership. Disabled entries do not submit; read-only entries do. Native reset restores uncontrolled initial values and discards drafts, respecting canceled reset events. Controlled values remain application-owned. These controls do not provide native `required` validation; applications validate submitted data and can use their Form messages.
+
+## Border ownership
+
+The embedded panel defaults to `frame="none"` and paints no outer edge or day-cell borders. `frame="outline"` supplies an independent panel outline when needed. Popups always use an unframed panel because Popover owns their surface and outer border. The picker owns its functional trigger outline and internal footer separator.
+
+Grid owns region seams and outer frames. Put an unframed DatePickerPanel directly in an unpadded GridItem; add GridItem padding when an inset is desired. Do not target private date cells from Layout styles or wrap a framed panel flush inside another frame.
+
+CSS owns date-grid geometry, range fills and container reflow. CVA owns density and frame variants. Existing Button, Popover, focus and theme contracts supply shared interactions and styling.
+
+See [component ownership](../../docs/component-ownership.md) and [release history](.changeset/history/).

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

@@ -0,0 +1,10 @@
+/**
+ * @author WMXPY
+ * @package Date Picker
+ * @namespace DatePicker
+ * @description Date Picker
+ */
+import type { SinglePickerOptions } from "../shared/picker-types";
+import type { FC } from "react";
+export type DatePickerProps = SinglePickerOptions;
+export declare const DatePicker: FC<DatePickerProps>;

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

@@ -0,0 +1,22 @@
+/**
+ * @author WMXPY
+ * @package Date Picker
+ * @namespace DatePickerPanel
+ * @description Date Picker Panel
+ */
+import type { DatePanelOptions, DateRange, DateValue } from "../shared/types";
+import { type ComponentPropsWithRef, type FC } from "react";
+export type DatePickerPanelProps = Omit<ComponentPropsWithRef<"div">, "defaultValue" | "onChange" | "children"> & DatePanelOptions & {
+    readonly frame?: "none" | "outline";
+} & ({
+    readonly mode?: "single";
+    readonly value?: DateValue | null;
+    readonly defaultValue?: DateValue | null;
+    readonly onValueChange?: (value: DateValue | null) => void;
+} | {
+    readonly mode: "range";
+    readonly value?: DateRange | null;
+    readonly defaultValue?: DateRange | null;
+    readonly onValueChange?: (value: DateRange | null) => void;
+});
+export declare const DatePickerPanel: FC<DatePickerPanelProps>;

package/dist/date-picker-panel/month.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @author WMXPY
+ * @package Date Picker
+ * @namespace DatePickerPanel
+ * @description Month
+ */
+import type { DateRange, DateValue } from "../shared/types";
+import type { FC, KeyboardEvent } from "react";
+export type MonthProps = {
+    readonly month: DateValue;
+    readonly label: string;
+    readonly days: readonly DateValue[];
+    readonly weekdays: readonly string[];
+    readonly getLabel: (day: DateValue) => string;
+    readonly getDayNumber: (day: DateValue) => number;
+    readonly focused: DateValue;
+    readonly today?: DateValue | undefined;
+    readonly selected: DateValue | null;
+    readonly range: DateRange | null;
+    readonly rangeMode: boolean;
+    readonly disabled: boolean;
+    readonly isAvailable: (day: DateValue) => boolean;
+    readonly onSelect: (day: DateValue) => void;
+    readonly onFocus: (day: DateValue) => void;
+    readonly onHover: (day: DateValue) => void;
+    readonly onKeyDown: (event: KeyboardEvent<HTMLButtonElement>, day: DateValue) => void;
+    readonly showCaption: boolean;
+};
+export declare const Month: FC<MonthProps>;

package/dist/date-picker-panel/style.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @author WMXPY
+ * @package Date Picker
+ * @namespace DatePickerPanel
+ * @description Style
+ */
+export declare const panelStyles: (props?: ({
+    frame?: "none" | "outline" | null | undefined;
+    size?: "standard" | "small" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;

package/dist/date-picker-panel/use-panel.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @author WMXPY
+ * @package Date Picker
+ * @namespace DatePickerPanel
+ * @description Use Panel
+ */
+import type { DatePanelOptions, DateRange, DateValue } from "../shared/types";
+import type { KeyboardEvent } from "react";
+type PanelStateOptions = DatePanelOptions & {
+    readonly mode: "single" | "range" | undefined;
+    readonly value: DateValue | DateRange | null | undefined;
+    readonly defaultValue: DateValue | DateRange | null | undefined;
+    readonly onValueChange: (value: DateValue | DateRange | null) => void;
+};
+export declare const usePanel: (props: PanelStateOptions) => {
+    value: string | DateRange | null;
+    month: string;
+    visibleDays: string[];
+    focused: string;
+    hovered: string | null;
+    setHovered: import("react").Dispatch<import("react").SetStateAction<string | null>>;
+    setFocused: import("react").Dispatch<import("react").SetStateAction<string>>;
+    element: import("react").RefObject<HTMLDivElement | null>;
+    eligible: (day: DateValue) => boolean;
+    select: (day: DateValue) => void;
+    onKeyDown: (event: KeyboardEvent<HTMLButtonElement>, day: DateValue) => void;
+    canPrevious: boolean;
+    canNext: boolean;
+    previous: () => void;
+    next: () => void;
+};
+export {};

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

@@ -0,0 +1,10 @@
+/**
+ * @author WMXPY
+ * @package Date Picker
+ * @namespace DateRangePicker
+ * @description Date Range Picker
+ */
+import type { RangePickerOptions } from "../shared/picker-types";
+import type { FC } from "react";
+export type DateRangePickerProps = RangePickerOptions;
+export declare const DateRangePicker: FC<DateRangePickerProps>;

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @author WMXPY
+ * @package Date Picker
+ * @namespace Root
+ * @description Index
+ */
+export type { DatePickerProps } from "./date-picker/date-picker";
+export { DatePicker } from "./date-picker/date-picker";
+export type { DatePickerPanelProps } from "./date-picker-panel/date-picker-panel";
+export { DatePickerPanel } from "./date-picker-panel/date-picker-panel";
+export type { DateRangePickerProps } from "./date-range-picker/date-range-picker";
+export { DateRangePicker } from "./date-range-picker/date-range-picker";
+export type { PickerLabels } from "./shared/picker-types";
+export type { DateConstraints, DatePanelLabels, DatePanelOptions, DateRange, DateValue } from "./shared/types";