chrona-react 0.3.1 → 0.3.3

package/README.md

@@ -6,7 +6,7 @@ values, no free-form date parsing, and no CSS — you own every pixel.
 Part of [Chrona](https://github.com/devlinduldulao/chrona). Built on
 [`chrona-core`](https://www.npmjs.com/package/chrona-core).
 
-> **Status: experimental 0.3.1.** Public APIs and styling attributes are not
+> **Status: experimental 0.3.3.** Public APIs and styling attributes are not
 > frozen for v1. 0.3.0 changes when a field reports a value and leaves `today`
 > to the client; 0.2.0 changed the Calendar cell anatomy. See the
 > [changelog](./CHANGELOG.md). Automated axe checks pass, but no screen-reader
@@ -128,6 +128,12 @@ A barrel export is also available. Matching hooks — `useCalendar`,
 
 ## Styling And Forms
 
+There is a starter stylesheet at
+[`docs/starter.css`](https://github.com/devlinduldulao/chrona/blob/main/docs/starter.css)
+— copy it in and edit it. It styles every part these packages emit, takes its
+colours from eight custom properties, and exists so that the first two hundred
+lines of CSS are not yours to write.
+
 Style via `data-scope`, `data-part`, and state attributes: `data-selected`,
 `data-focused`, `data-today`, `data-disabled`, `data-unavailable`,
 `data-outside-month`, `data-in-range`, `data-range-start`, `data-range-end`,
@@ -308,17 +314,11 @@ import { DatePicker } from "chrona-react";
   so it can be set from a touch keyboard; it has no pointer affordance of its
   own, so give readers a keyboard path to it.
 
-## Server Rendering
+## Next.js App Router
 
-These components use state and context, so they carry a `"use client"`
-directive. Importing them from a Server Component is safe — the framework moves
-the import across the boundary — but the module that *renders* them still has to
-be a client module, so mark it `"use client"` as usual.
-
-The polyfill import is a side effect, so it has to reach the *client* bundle.
-Importing `temporal-polyfill/global` from a Server Component file installs
-Temporal on the server only. Put it at the top of a `"use client"` module that
-always loads — a providers file, for example — so it runs before hydration:
+Two files. Both need `"use client"`, and both need the polyfill import — that
+second one is the part people lose an afternoon to, so it is explained under
+the code.
 
 ```tsx
 // app/providers.tsx
@@ -328,26 +328,72 @@ import "temporal-polyfill/global";
 import { ChronaProvider } from "chrona-react";
 
 export function Providers({ children }: { children: React.ReactNode }) {
-  return <ChronaProvider locale="en-US" timeZone="Europe/Copenhagen">{children}</ChronaProvider>;
+  return (
+    <ChronaProvider locale="en-US" timeZone="Europe/Copenhagen">
+      {children}
+    </ChronaProvider>
+  );
 }
 ```
 
-That covers the client bundle before hydration. It does not order Node module
-evaluation. If another `"use client"` file reads `Temporal` at module scope
-(`const reference = Temporal.PlainDate.from(...)` at the top of `page.tsx`),
-Next.js may evaluate that file during SSR before `providers.tsx` has run and
-throw `ReferenceError: Temporal is not defined`. Import the polyfill at the top
-of that file too, or move the call inside the component body:
+Render that from `app/layout.tsx` — which stays a Server Component — wrapping
+`{children}`.
 
 ```tsx
+// app/booking-form.tsx
 "use client";
 
+// Needed here as well as in providers.tsx: this module reads Temporal at module
+// scope, and Next.js does not promise providers.tsx has been evaluated first.
 import "temporal-polyfill/global";
+
+import { useState } from "react";
 import { Calendar } from "chrona-react";
 
 const REFERENCE = Temporal.PlainDate.from({ year: 2026, month: 9, day: 16 });
+
+export function BookingForm() {
+  const [value, setValue] = useState<Temporal.PlainDate | null>(null);
+
+  return (
+    <Calendar.Root value={value} onChange={setValue} placeholderValue={REFERENCE} fixedWeeks>
+      <Calendar.Header>
+        <Calendar.PrevButton />
+        <Calendar.Heading />
+        <Calendar.NextButton />
+      </Calendar.Header>
+      <Calendar.Grid>
+        <Calendar.GridHeader />
+        <Calendar.GridBody />
+      </Calendar.Grid>
+      <Calendar.HiddenInput name="bookingDate" />
+    </Calendar.Root>
+  );
+}
 ```
 
+Why the polyfill appears twice: importing it is a side effect, so it has to
+reach the *client* bundle — importing it from a Server Component installs
+Temporal on the server only. `providers.tsx` covers the client before
+hydration, but it does not order Node's module evaluation during SSR. A
+`"use client"` file that reads `Temporal` at module scope can be evaluated
+before `providers.tsx` and throw `ReferenceError: Temporal is not defined`.
+Import it at the top of that file too, or move the call inside the component.
+
+`placeholderValue` is not decoration: it is what a server-rendered calendar
+opens on. See [Give every calendar a reference date](#give-every-calendar-a-reference-date).
+
+`chrona-react` also ships an `AGENTS.md`, written for coding agents and short
+enough to be worth reading yourself — it lists the SSR pitfalls, the part
+anatomy, field draft behaviour, and what is deliberately not implemented.
+
+## Server Rendering
+
+These components use state and context, so they carry a `"use client"`
+directive. Importing them from a Server Component is safe — the framework moves
+the import across the boundary — but the module that *renders* them still has to
+be a client module.
+
 Pass the same reference date, value, locale, and time zone on server and client.
 
 ### Today

package/dist/calendar.d.ts

@@ -0,0 +1,142 @@
+import * as temporal_spec from 'temporal-spec';
+import { P as PartProps, H as HiddenInputProps, C as ChronaConfig } from './form-BCAGbNh-.js';
+import * as chrona_core from 'chrona-core';
+import { CalendarOptions, PlainDate, CalendarEvent } from 'chrona-core';
+import * as React from 'react';
+
+interface CalendarProps extends CalendarOptions {
+    defaultValue?: PlainDate | null;
+    defaultFocusedValue?: PlainDate;
+    onChange?: (value: PlainDate | null) => void;
+    onSelect?: (value: PlainDate) => void;
+    onFocusedValueChange?: (value: PlainDate) => void;
+    id?: string;
+}
+declare function useCalendar(props?: CalendarProps): {
+    state: chrona_core.CalendarState;
+    options: CalendarProps & ChronaConfig;
+    send: (event: CalendarEvent) => void;
+    rootRef: React.RefObject<HTMLElement | null>;
+    announcement: string;
+    api: {
+        getRootProps: () => {
+            dir: "ltr" | "rtl" | undefined;
+            "data-disabled": string | undefined;
+            "data-readonly": string | undefined;
+            "data-scope": string;
+            "data-part": string;
+        };
+        getGridProps: (month?: temporal_spec.Temporal.PlainDate) => {
+            role: "grid";
+            "aria-label": string;
+            "aria-readonly": true | undefined;
+            "aria-disabled": true | undefined;
+            "data-scope": string;
+            "data-part": string;
+        };
+        getCellProps: (date: PlainDate, month?: temporal_spec.Temporal.PlainDate) => {
+            "data-date": string;
+            "data-selected": string | undefined;
+            "data-focused": string | undefined;
+            "data-disabled": string | undefined;
+            "data-unavailable": string | undefined;
+            "data-outside-month": string | undefined;
+            "data-today": string | undefined;
+            role: "gridcell";
+            "aria-selected": boolean;
+            "aria-disabled": true | undefined;
+            "data-scope": string;
+            "data-part": string;
+        };
+        getCellTriggerProps: (date: PlainDate, month?: temporal_spec.Temporal.PlainDate) => {
+            "data-date": string;
+            "data-selected": string | undefined;
+            "data-focused": string | undefined;
+            "data-disabled": string | undefined;
+            "data-unavailable": string | undefined;
+            "data-outside-month": string | undefined;
+            "data-today": string | undefined;
+            id: string;
+            type: "button";
+            tabIndex: number;
+            "aria-label": string;
+            "aria-disabled": true | undefined;
+            "aria-current": "date" | undefined;
+            "data-scope": string;
+            "data-part": string;
+        };
+        getPrevButtonProps: () => {
+            type: "button";
+            "aria-label": string;
+            disabled: boolean;
+            "data-scope": string;
+            "data-part": string;
+        };
+        getNextButtonProps: () => {
+            type: "button";
+            "aria-label": string;
+            disabled: boolean;
+            "data-scope": string;
+            "data-part": string;
+        };
+    };
+    months: temporal_spec.Temporal.PlainDate[];
+};
+type CalendarContextValue = ReturnType<typeof useCalendar>;
+declare function CalendarRoot({ children, asChild, className, style, ...props }: CalendarProps & Pick<PartProps, "children" | "asChild" | "className" | "style">): React.JSX.Element;
+declare function CalendarSurface({ calendar, ...props }: PartProps & {
+    calendar: CalendarContextValue;
+}): React.JSX.Element;
+interface Weekday {
+    date: PlainDate;
+    label: string;
+}
+declare function HiddenInput(props: HiddenInputProps): React.JSX.Element;
+declare const Calendar: {
+    Root: typeof CalendarRoot;
+    Header: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    Heading: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    PrevButton: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    NextButton: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    Grid: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
+        asChild?: boolean;
+    } & {
+        monthIndex?: number;
+    } & React.RefAttributes<HTMLElement>>;
+    GridHeader: React.ForwardRefExoticComponent<Omit<PartProps, "children"> & {
+        children?: (day: Weekday) => React.ReactNode;
+    } & React.RefAttributes<HTMLElement>>;
+    HeaderCell: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
+        asChild?: boolean;
+    } & {
+        day: Weekday;
+    } & React.RefAttributes<HTMLElement>>;
+    GridBody: React.ForwardRefExoticComponent<Omit<PartProps, "children"> & {
+        children?: (date: PlainDate) => React.ReactNode;
+    } & React.RefAttributes<HTMLElement>>;
+    Cell: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
+        asChild?: boolean;
+    } & {
+        date: PlainDate;
+    } & React.RefAttributes<HTMLElement>>;
+    CellTrigger: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    LiveRegion: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    ClearButton: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    HiddenInput: typeof HiddenInput;
+};
+
+export { Calendar, type CalendarProps, CalendarRoot, CalendarSurface, type Weekday, useCalendar };

package/dist/date-field.d.ts

@@ -0,0 +1,74 @@
+import { P as PartProps, H as HiddenInputProps, C as ChronaConfig } from './form-BCAGbNh-.js';
+import * as chrona_core from 'chrona-core';
+import * as React from 'react';
+import { F as FieldProps } from './field-DayikvR6.js';
+
+type DateFieldProps = FieldProps<"date">;
+declare const DateField: {
+    Root: ({ children, asChild, className, style, ...props }: FieldProps<"date"> & Pick<PartProps, "className" | "style" | "children" | "asChild">) => React.JSX.Element;
+    Label: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    Field: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    Segment: React.ForwardRefExoticComponent<Omit<Omit<React.DetailedHTMLProps<React.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref">, "defaultValue" | "children" | "onChange" | "type" | "value"> & {
+        type: chrona_core.SegmentType;
+    } & React.RefAttributes<HTMLInputElement>>;
+    HiddenInput: (props: HiddenInputProps) => React.JSX.Element;
+    ClearButton: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    LiveRegion: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+};
+declare function useDateField(props?: DateFieldProps): {
+    id: string;
+    state: chrona_core.FieldState<"date">;
+    options: FieldProps<"date"> & ChronaConfig;
+    send: (event: chrona_core.FieldEvent) => void;
+    reset: () => void;
+    moveFocus: (segment: chrona_core.SegmentType, offset: number) => void;
+    groupRef: React.RefObject<HTMLElement | null>;
+    announcement: string;
+    registerLabel: React.Dispatch<React.SetStateAction<boolean>>;
+    api: {
+        segments: {
+            type: chrona_core.SegmentType | "literal";
+            value: string;
+        }[];
+        getGroupProps: () => {
+            role: "group";
+            "aria-labelledby": string | undefined;
+            "aria-describedby": string | undefined;
+            "aria-invalid": true | undefined;
+            "data-scope": string;
+            "data-part": string;
+            "data-invalid": string | undefined;
+            "data-disabled": string | undefined;
+            "data-readonly": string | undefined;
+            dir: "ltr" | "rtl" | undefined;
+        };
+        getSegmentProps: (segment: chrona_core.SegmentType) => {
+            role: "spinbutton";
+            "aria-label": string;
+            "aria-valuemin": number;
+            "aria-valuemax": number;
+            "aria-valuenow": number | undefined;
+            "aria-valuetext": string;
+            "aria-required": true | undefined;
+            "aria-invalid": true | undefined;
+            "aria-describedby": string | undefined;
+            "aria-readonly": true | undefined;
+            "data-scope": string;
+            "data-part": string;
+            "data-segment": chrona_core.SegmentName;
+            "data-placeholder": string | undefined;
+            "data-invalid": string | undefined;
+            display: string;
+        };
+    };
+};
+
+export { DateField, type DateFieldProps, useDateField };

package/dist/date-picker.d.ts

@@ -0,0 +1,69 @@
+import { P as PartProps, H as HiddenInputProps } from './form-BCAGbNh-.js';
+import * as chrona_core from 'chrona-core';
+import { PlainDate, PickerEvent } from 'chrona-core';
+import * as React from 'react';
+import { CalendarProps } from './calendar.js';
+import { DateFieldProps } from './date-field.js';
+import 'temporal-spec';
+import './field-DayikvR6.js';
+
+interface DatePickerProps extends DateFieldProps {
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    modal?: boolean;
+    timeZone?: string;
+    firstDayOfWeek?: number;
+    fixedWeeks?: boolean;
+    numberOfMonths?: number;
+    pagedNavigation?: boolean;
+}
+interface PickerContext {
+    props: DatePickerProps;
+    options: DatePickerProps;
+    state: {
+        value: PlainDate | null;
+        open: boolean;
+    };
+    id: string;
+    value: PlainDate | null;
+    change: (value: PlainDate | null) => void;
+    open: boolean;
+    send: (event: PickerEvent) => void;
+    trigger: {
+        current: HTMLElement | null;
+    };
+    labelled: boolean;
+    registerLabel: (present: boolean) => void;
+}
+declare function Root({ children, asChild, className, style, ...input }: DatePickerProps & Pick<PartProps, "children" | "asChild" | "className" | "style">): React.JSX.Element;
+declare function useDatePicker(input?: DatePickerProps): PickerContext;
+declare function PickerCalendar({ children, ...props }: Omit<CalendarProps, "value" | "defaultValue" | "onChange"> & Pick<PartProps, "children" | "className" | "style">): React.JSX.Element;
+declare const DatePicker: {
+    Root: typeof Root;
+    Label: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    Field: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    Segment: React.ForwardRefExoticComponent<Omit<Omit<React.DetailedHTMLProps<React.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref">, "defaultValue" | "children" | "onChange" | "type" | "value"> & {
+        type: chrona_core.SegmentType;
+    } & React.RefAttributes<HTMLInputElement>>;
+    HiddenInput: (props: HiddenInputProps) => React.JSX.Element;
+    ClearButton: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    LiveRegion: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    Trigger: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    Popover: React.ForwardRefExoticComponent<Omit<Omit<React.DetailedHTMLProps<React.DialogHTMLAttributes<HTMLDialogElement>, HTMLDialogElement>, "ref">, "open"> & {
+        anchored?: boolean;
+    } & React.RefAttributes<HTMLDialogElement>>;
+    Calendar: typeof PickerCalendar;
+};
+
+export { DatePicker, type DatePickerProps, useDatePicker };

package/dist/field-DayikvR6.d.ts

@@ -0,0 +1,11 @@
+import { FieldKind, FieldOptions, FieldValue, FieldInvalidReason } from 'chrona-core';
+
+interface FieldProps<Kind extends FieldKind> extends FieldOptions<Kind> {
+    defaultValue?: FieldValue<Kind> | null;
+    onChange?: (value: FieldValue<Kind> | null) => void;
+    onInvalid?: (reason: FieldInvalidReason) => void;
+    id?: string;
+    describedBy?: string;
+}
+
+export type { FieldProps as F };

package/dist/form-BCAGbNh-.d.ts

@@ -0,0 +1,20 @@
+import * as React from 'react';
+import { Translations } from 'chrona-core';
+
+interface ChronaConfig {
+    locale?: string;
+    timeZone?: string;
+    dir?: "ltr" | "rtl";
+    translations?: Partial<Translations>;
+}
+declare function ChronaProvider({ children, ...config }: ChronaConfig & {
+    children: React.ReactNode;
+}): React.JSX.Element;
+
+type PartProps = React.HTMLAttributes<HTMLElement> & {
+    asChild?: boolean;
+};
+
+type HiddenInputProps = Omit<React.ComponentPropsWithoutRef<"input">, "type" | "value" | "defaultValue" | "onChange">;
+
+export { type ChronaConfig as C, type HiddenInputProps as H, type PartProps as P, ChronaProvider as a };

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { Calendar, CalendarProps, CalendarRoot, Weekday, useCalendar } from './calendar.js';
+export { C as ChronaConfig, a as ChronaProvider } from './form-BCAGbNh-.js';
+export { DateField, DateFieldProps, useDateField } from './date-field.js';
+export { TimeField, TimeFieldProps, useTimeField } from './time-field.js';
+export { DatePicker, DatePickerProps, useDatePicker } from './date-picker.js';
+export { RangeCalendar, RangeCalendarProps, useRangeCalendar } from './range-calendar.js';
+import 'temporal-spec';
+import 'chrona-core';
+import 'react';
+import './field-DayikvR6.js';

package/dist/range-calendar.d.ts

@@ -0,0 +1,233 @@
+import { CalendarProps, Weekday } from './calendar.js';
+import * as chrona_core from 'chrona-core';
+import { DateRange, PlainDate, RangeEvent } from 'chrona-core';
+import * as temporal_spec from 'temporal-spec';
+import { P as PartProps, H as HiddenInputProps, C as ChronaConfig } from './form-BCAGbNh-.js';
+import * as React from 'react';
+
+interface RangeCalendarProps extends Omit<CalendarProps, "value" | "defaultValue" | "onChange"> {
+    value?: DateRange | null;
+    defaultValue?: DateRange | null;
+    onChange?: (value: DateRange | null) => void;
+    onRangeStartChange?: (value: PlainDate | null) => void;
+    onInvalid?: () => void;
+}
+declare function useRangeCalendar(input?: RangeCalendarProps): {
+    state: {
+        value: DateRange | null;
+        anchor: PlainDate | null;
+        preview: PlainDate | null;
+        invalid: boolean;
+    };
+    send: (event: RangeEvent) => void;
+    announcement: string;
+    props: RangeCalendarProps & ChronaConfig;
+    options: RangeCalendarProps & ChronaConfig;
+    api: {
+        getCellProps: (date: PlainDate, month?: PlainDate) => {
+            "data-scope": string;
+            "data-selected": string | undefined;
+            "data-in-range": string | undefined;
+            "data-range-start": string | undefined;
+            "data-range-end": string | undefined;
+            "data-preview": string | undefined;
+            "data-invalid": string | undefined;
+            "aria-selected": boolean;
+            "data-date": string;
+            "data-focused": string | undefined;
+            "data-disabled": string | undefined;
+            "data-unavailable": string | undefined;
+            "data-outside-month": string | undefined;
+            "data-today": string | undefined;
+            role: "gridcell";
+            "aria-disabled": true | undefined;
+            "data-part": string;
+        };
+        getCellTriggerProps: (date: PlainDate, month?: PlainDate) => {
+            "data-scope": string;
+            "data-selected": string | undefined;
+            "data-in-range": string | undefined;
+            "data-range-start": string | undefined;
+            "data-range-end": string | undefined;
+            "data-preview": string | undefined;
+            "data-invalid": string | undefined;
+            "data-date": string;
+            "data-focused": string | undefined;
+            "data-disabled": string | undefined;
+            "data-unavailable": string | undefined;
+            "data-outside-month": string | undefined;
+            "data-today": string | undefined;
+            id: string;
+            type: "button";
+            tabIndex: number;
+            "aria-label": string;
+            "aria-disabled": true | undefined;
+            "aria-current": "date" | undefined;
+            "data-part": string;
+        };
+        getRootProps: () => {
+            dir: "ltr" | "rtl" | undefined;
+            "data-disabled": string | undefined;
+            "data-readonly": string | undefined;
+            "data-scope": string;
+            "data-part": string;
+        };
+        getGridProps: (month?: temporal_spec.Temporal.PlainDate) => {
+            role: "grid";
+            "aria-label": string;
+            "aria-readonly": true | undefined;
+            "aria-disabled": true | undefined;
+            "data-scope": string;
+            "data-part": string;
+        };
+        getPrevButtonProps: () => {
+            type: "button";
+            "aria-label": string;
+            disabled: boolean;
+            "data-scope": string;
+            "data-part": string;
+        };
+        getNextButtonProps: () => {
+            type: "button";
+            "aria-label": string;
+            disabled: boolean;
+            "data-scope": string;
+            "data-part": string;
+        };
+    };
+    rootRef: React.RefObject<HTMLElement | null>;
+    months: temporal_spec.Temporal.PlainDate[];
+    reset(): void;
+    calendar: {
+        api: {
+            getCellProps: (date: PlainDate, month?: PlainDate) => {
+                "data-scope": string;
+                "data-selected": string | undefined;
+                "data-in-range": string | undefined;
+                "data-range-start": string | undefined;
+                "data-range-end": string | undefined;
+                "data-preview": string | undefined;
+                "data-invalid": string | undefined;
+                "aria-selected": boolean;
+                "data-date": string;
+                "data-focused": string | undefined;
+                "data-disabled": string | undefined;
+                "data-unavailable": string | undefined;
+                "data-outside-month": string | undefined;
+                "data-today": string | undefined;
+                role: "gridcell";
+                "aria-disabled": true | undefined;
+                "data-part": string;
+            };
+            getCellTriggerProps: (date: PlainDate, month?: PlainDate) => {
+                "data-scope": string;
+                "data-selected": string | undefined;
+                "data-in-range": string | undefined;
+                "data-range-start": string | undefined;
+                "data-range-end": string | undefined;
+                "data-preview": string | undefined;
+                "data-invalid": string | undefined;
+                "data-date": string;
+                "data-focused": string | undefined;
+                "data-disabled": string | undefined;
+                "data-unavailable": string | undefined;
+                "data-outside-month": string | undefined;
+                "data-today": string | undefined;
+                id: string;
+                type: "button";
+                tabIndex: number;
+                "aria-label": string;
+                "aria-disabled": true | undefined;
+                "aria-current": "date" | undefined;
+                "data-part": string;
+            };
+            getRootProps: () => {
+                dir: "ltr" | "rtl" | undefined;
+                "data-disabled": string | undefined;
+                "data-readonly": string | undefined;
+                "data-scope": string;
+                "data-part": string;
+            };
+            getGridProps: (month?: temporal_spec.Temporal.PlainDate) => {
+                role: "grid";
+                "aria-label": string;
+                "aria-readonly": true | undefined;
+                "aria-disabled": true | undefined;
+                "data-scope": string;
+                "data-part": string;
+            };
+            getPrevButtonProps: () => {
+                type: "button";
+                "aria-label": string;
+                disabled: boolean;
+                "data-scope": string;
+                "data-part": string;
+            };
+            getNextButtonProps: () => {
+                type: "button";
+                "aria-label": string;
+                disabled: boolean;
+                "data-scope": string;
+                "data-part": string;
+            };
+        };
+        state: chrona_core.CalendarState;
+        options: CalendarProps & ChronaConfig;
+        send: (event: chrona_core.CalendarEvent) => void;
+        rootRef: React.RefObject<HTMLElement | null>;
+        announcement: string;
+        months: temporal_spec.Temporal.PlainDate[];
+    };
+};
+declare function Root({ children, asChild, className, style, ...props }: RangeCalendarProps & Pick<PartProps, "children" | "asChild" | "className" | "style">): React.JSX.Element;
+declare function HiddenInput({ name, form, id, disabled, ...inputProps }: HiddenInputProps & {
+    name: string;
+}): React.JSX.Element;
+declare const RangeCalendar: {
+    Root: typeof Root;
+    Cell: React.ForwardRefExoticComponent<Omit<React.HTMLAttributes<HTMLElement> & {
+        asChild?: boolean;
+    } & {
+        date: PlainDate;
+    } & React.RefAttributes<HTMLElement>, "ref"> & React.RefAttributes<HTMLElement>>;
+    GridBody: React.ForwardRefExoticComponent<Omit<Omit<PartProps, "children"> & {
+        children?: (date: PlainDate) => React.ReactNode;
+    } & React.RefAttributes<HTMLElement>, "ref"> & React.RefAttributes<HTMLElement>>;
+    LiveRegion: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    ClearButton: React.ForwardRefExoticComponent<Omit<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>, "ref"> & React.RefAttributes<HTMLElement>>;
+    HiddenInput: typeof HiddenInput;
+    Header: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    Heading: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    PrevButton: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    NextButton: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    Grid: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
+        asChild?: boolean;
+    } & {
+        monthIndex?: number;
+    } & React.RefAttributes<HTMLElement>>;
+    GridHeader: React.ForwardRefExoticComponent<Omit<PartProps, "children"> & {
+        children?: (day: Weekday) => React.ReactNode;
+    } & React.RefAttributes<HTMLElement>>;
+    HeaderCell: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
+        asChild?: boolean;
+    } & {
+        day: Weekday;
+    } & React.RefAttributes<HTMLElement>>;
+    CellTrigger: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+};
+
+export { RangeCalendar, type RangeCalendarProps, useRangeCalendar };

package/dist/time-field.d.ts

@@ -0,0 +1,74 @@
+import { P as PartProps, H as HiddenInputProps, C as ChronaConfig } from './form-BCAGbNh-.js';
+import * as chrona_core from 'chrona-core';
+import * as React from 'react';
+import { F as FieldProps } from './field-DayikvR6.js';
+
+type TimeFieldProps = FieldProps<"time">;
+declare const TimeField: {
+    Root: ({ children, asChild, className, style, ...props }: FieldProps<"time"> & Pick<PartProps, "className" | "style" | "children" | "asChild">) => React.JSX.Element;
+    Label: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    Field: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    Segment: React.ForwardRefExoticComponent<Omit<Omit<React.DetailedHTMLProps<React.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref">, "defaultValue" | "children" | "onChange" | "type" | "value"> & {
+        type: chrona_core.SegmentType;
+    } & React.RefAttributes<HTMLInputElement>>;
+    HiddenInput: (props: HiddenInputProps) => React.JSX.Element;
+    ClearButton: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+    LiveRegion: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLElement>>;
+};
+declare function useTimeField(props?: TimeFieldProps): {
+    id: string;
+    state: chrona_core.FieldState<"time">;
+    options: FieldProps<"time"> & ChronaConfig;
+    send: (event: chrona_core.FieldEvent) => void;
+    reset: () => void;
+    moveFocus: (segment: chrona_core.SegmentType, offset: number) => void;
+    groupRef: React.RefObject<HTMLElement | null>;
+    announcement: string;
+    registerLabel: React.Dispatch<React.SetStateAction<boolean>>;
+    api: {
+        segments: {
+            type: chrona_core.SegmentType | "literal";
+            value: string;
+        }[];
+        getGroupProps: () => {
+            role: "group";
+            "aria-labelledby": string | undefined;
+            "aria-describedby": string | undefined;
+            "aria-invalid": true | undefined;
+            "data-scope": string;
+            "data-part": string;
+            "data-invalid": string | undefined;
+            "data-disabled": string | undefined;
+            "data-readonly": string | undefined;
+            dir: "ltr" | "rtl" | undefined;
+        };
+        getSegmentProps: (segment: chrona_core.SegmentType) => {
+            role: "spinbutton";
+            "aria-label": string;
+            "aria-valuemin": number;
+            "aria-valuemax": number;
+            "aria-valuenow": number | undefined;
+            "aria-valuetext": string;
+            "aria-required": true | undefined;
+            "aria-invalid": true | undefined;
+            "aria-describedby": string | undefined;
+            "aria-readonly": true | undefined;
+            "data-scope": string;
+            "data-part": string;
+            "data-segment": chrona_core.SegmentName;
+            "data-placeholder": string | undefined;
+            "data-invalid": string | undefined;
+            display: string;
+        };
+    };
+};
+
+export { TimeField, type TimeFieldProps, useTimeField };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrona-react",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Headless Temporal-native React date and time primitives",
   "type": "module",
   "license": "MIT",
@@ -61,7 +61,7 @@
     }
   },
   "dependencies": {
-    "chrona-core": "^0.3.1"
+    "chrona-core": "^0.3.3"
   },
   "peerDependencies": {
     "react": ">=18.0.0",