@salt-ds/lab 1.0.0-alpha.51 → 1.0.0-alpha.52

package/dist-types/date-input/DateInputRange.d.ts

@@ -0,0 +1,150 @@
+import { type DateValue } from "@internationalized/date";
+import { type InputProps } from "@salt-ds/core";
+import { type ChangeEvent, type ComponentPropsWithoutRef, type InputHTMLAttributes, type ReactNode, type Ref, type SyntheticEvent } from "react";
+import { type DateRangeSelection } from "../calendar";
+import type { DateInputSingleParserError } from "./DateInputSingle";
+/**
+ * Date error produced by DateInputRange parser.
+ */
+export declare type DateInputRangeParserError = string | false;
+/**
+ * DateInputRange raw value or null if no date is defined.
+ */
+export declare type DateInputRangeValue = {
+    startDate?: string | null;
+    endDate?: string | null;
+};
+/**
+ * Return value of DateInputRange parser.
+ * @template T
+ */
+export interface DateInputRangeParserResult<T = DateValue | null> {
+    /**
+     * The parsed date value.
+     */
+    date: T;
+    /**
+     * The error encountered during parsing, if any.
+     */
+    error: DateInputRangeParserError;
+}
+/**
+ * Date Range error returned with selected date to indicate invalid dates.
+ */
+export declare type DateInputRangeError = {
+    /**
+     * The error for the start date.
+     */
+    startDate: DateInputSingleParserError;
+    /**
+     * The error for the end date.
+     */
+    endDate: DateInputSingleParserError;
+};
+/**
+ * Props for the DateInputRange component.
+ * @template T
+ */
+export interface DateInputRangeProps<T = DateRangeSelection> extends Omit<ComponentPropsWithoutRef<"div">, "defaultValue" | "onChange">, Omit<InputProps, "defaultValue" | "inputRef" | "value" | "onChange"> {
+    /**
+     * The aria-label for accessibility.
+     */
+    ariaLabel?: string;
+    /**
+     * Styling variant with full border. Defaults to false.
+     */
+    bordered?: boolean;
+    /**
+     * The marker to use in an empty read-only DateInput.
+     * Use `''` to disable this feature. Defaults to '—'.
+     */
+    emptyReadOnlyMarker?: string;
+    /**
+     * End adornment component.
+     */
+    endAdornment?: ReactNode;
+    /**
+     * Attributes applied to the start `input` element.
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dateInput#Attributes
+     */
+    startInputProps?: InputHTMLAttributes<HTMLInputElement>;
+    /**
+     * Attributes applied to the end `input` element.
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dateInput#Attributes
+     */
+    endInputProps?: InputHTMLAttributes<HTMLInputElement>;
+    /**
+     * If `true`, the component is read-only.
+     */
+    readOnly?: boolean;
+    /**
+     * Validation status.
+     */
+    validationStatus?: "error" | "warning" | "success";
+    /**
+     * Styling variant. Defaults to "primary".
+     */
+    variant?: "primary" | "secondary";
+    /**
+     * Function to format the input value.
+     */
+    format?: (date: DateValue | null) => string;
+    /**
+     * Optional ref for the start input component.
+     */
+    startInputRef?: Ref<HTMLInputElement>;
+    /**
+     * Optional ref for the end input component.
+     */
+    endInputRef?: Ref<HTMLInputElement>;
+    /**
+     * Input value. Use when the input value is controlled.
+     */
+    value?: DateInputRangeValue;
+    /**
+     * The initial input value. Use when the component is uncontrolled.
+     */
+    defaultValue?: DateInputRangeValue;
+    /**
+     * The date value. Use when the component is controlled.
+     */
+    date?: T | null;
+    /**
+     * The initial selected date value. Use when the component is uncontrolled.
+     */
+    defaultDate?: T | null;
+    /**
+     * Callback fired when the input value changes.
+     * @param event - The change event.
+     * @param date - The new date input range value.
+     */
+    onChange?: (event: ChangeEvent<HTMLInputElement>, date: DateInputRangeValue) => void;
+    /**
+     * Callback fired when the selected date changes.
+     * @param event - The synthetic event.
+     * @param date - The new date value.
+     * @param error - The date input range error.
+     */
+    onDateChange?: (event: SyntheticEvent, date: T | null, error: DateInputRangeError) => void;
+    /**
+     * Called when input values change, either due to user interaction or programmatic formatting of valid dates.
+     * @param newValue - The new date input range value.
+     * @param isFormatted - Whether the value is formatted.
+     */
+    onDateValueChange?: (newValue: DateInputRangeValue, isFormatted: boolean) => void;
+    /**
+     * Function to parse date string to valid `DateValue` or null, if invalid.
+     * @param inputDate - The input date string.
+     * @returns The result of the date input range parser.
+     */
+    parse?: (inputDate: string) => DateInputRangeParserResult;
+    /**
+     * Locale of the entered date.
+     */
+    locale?: string;
+    /**
+     * Timezone of the entered date.
+     */
+    timeZone?: string;
+}
+export declare const DateInputRange: import("react").ForwardRefExoticComponent<DateInputRangeProps<DateRangeSelection> & import("react").RefAttributes<HTMLDivElement>>;

package/dist-types/date-input/DateInputSingle.d.ts

@@ -0,0 +1,117 @@
+import { type DateValue } from "@internationalized/date";
+import { type ComponentPropsWithoutRef, type InputHTMLAttributes, type ReactNode, type RefObject, type SyntheticEvent } from "react";
+import { type SingleDateSelection } from "../calendar";
+/**
+ * Date error produced by DateInputSingle parser.
+ */
+export declare type DateInputSingleParserError = string | false;
+/**
+ * Date error produced by DateInputSingle parser.
+ */
+export declare type DateInputSingleError = DateInputSingleParserError;
+/**
+ * Return value of DateInputSingle parser.
+ * @template T
+ */
+export interface DateInputSingleParserResult<T = DateValue | null> {
+    /**
+     * The parsed date value.
+     */
+    date: T;
+    /**
+     * The error encountered during parsing, if any.
+     */
+    error: DateInputSingleParserError;
+}
+/**
+ * Props for the DateInputSingle component.
+ * @template T
+ */
+export interface DateInputSingleProps<T = SingleDateSelection> extends Omit<ComponentPropsWithoutRef<"div">, "defaultValue">, Pick<ComponentPropsWithoutRef<"input">, "disabled" | "value" | "defaultValue" | "placeholder"> {
+    /**
+     * The aria-label for accessibility.
+     */
+    ariaLabel?: string;
+    /**
+     * Styling variant with full border. Defaults to false.
+     */
+    bordered?: boolean;
+    /**
+     * The marker to use in an empty read-only DateInput.
+     * Use `''` to disable this feature. Defaults to '—'.
+     */
+    emptyReadOnlyMarker?: string;
+    /**
+     * End adornment component.
+     */
+    endAdornment?: ReactNode;
+    /**
+     * Attributes applied to the `input` element.
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dateInput#Attributes
+     */
+    inputProps?: InputHTMLAttributes<HTMLInputElement>;
+    /**
+     * If `true`, the component is read-only.
+     */
+    readOnly?: boolean;
+    /**
+     * Validation status.
+     */
+    validationStatus?: "error" | "warning" | "success";
+    /**
+     * Styling variant. Defaults to "primary".
+     */
+    variant?: "primary" | "secondary";
+    /**
+     * Function to format the input value.
+     */
+    format?: (date: DateValue | null) => string;
+    /**
+     * Reference for the input.
+     */
+    inputRef?: RefObject<HTMLInputElement>;
+    /**
+     * Input value. Use when the input value is controlled.
+     */
+    value?: string;
+    /**
+     * The initial input value. Use when the component is uncontrolled.
+     */
+    defaultValue?: string;
+    /**
+     * The date value. Use when the component is controlled.
+     */
+    date?: T | null;
+    /**
+     * The initial selected date value. Use when the component is uncontrolled.
+     */
+    defaultDate?: T | null;
+    /**
+     * Callback fired when the selected date changes.
+     * @param event - The synthetic event.
+     * @param date - The new date value.
+     * @param error - The date input single error.
+     */
+    onDateChange?: (event: SyntheticEvent, date: T | null, error: DateInputSingleError) => void;
+    /**
+     * Function to parse date string to valid `DateValue` or null, if invalid or empty.
+     * @param inputDate - The input date string.
+     * @returns The result of the date input single parser.
+     */
+    parse?: (inputDate: string) => DateInputSingleParserResult;
+    /**
+     * Called when input value changes, either due to user interaction or programmatic formatting of valid dates.
+     * @param newValue - The new date input value.
+     * @param isFormatted - Whether the value is formatted.
+     */
+    onDateValueChange?: (newValue: string, isFormatted: boolean) => void;
+    /**
+     * Locale of the entered date.
+     */
+    locale?: string;
+    /**
+     * Timezone of the entered date.
+     */
+    timeZone?: string;
+}
+export declare const DateInputSingle: import("react").ForwardRefExoticComponent<DateInputSingleProps<DateValue> & import("react").RefAttributes<HTMLDivElement>>;

package/dist-types/date-input/index.d.ts

@@ -1 +1,3 @@
-export * from "./DateInput";
+export * from "./DateInputSingle";
+export * from "./DateInputRange";
+export * from "./utils";

package/dist-types/date-input/utils.d.ts

@@ -0,0 +1,43 @@
+import { CalendarDateTime, type DateValue, type TimeFields, ZonedDateTime } from "@internationalized/date";
+import type { DateRangeSelection, SingleDateSelection } from "../calendar";
+export declare type RangeTimeFields = {
+    startTime?: TimeFields;
+    endTime?: TimeFields;
+};
+/**
+ * Parses a string into a CalendarDate.
+ * @param inputDate - The input date string.
+ * @returns An object containing the parsed date and any error encountered.
+ */
+export declare function parseCalendarDate(inputDate: string): {
+    date: DateValue | null;
+    error: string | false;
+};
+/**
+ * Parses a string into a ZonedDateTime.
+ * @param inputDate - The input date string.
+ * @param timeZone - The time zone to use for parsing. Defaults to the local time zone.
+ * @returns An object containing the parsed date and any error encountered.
+ */
+export declare function parseZonedDateTime(inputDate: string, timeZone?: string): {
+    date: DateValue | null;
+    error: string | false;
+};
+/**
+ * Checks if a date supports time fields.
+ * @param date - The date to check.
+ * @returns `true` if the date supports time fields, otherwise `false`.
+ */
+export declare const dateSupportsTime: (date: DateValue) => date is CalendarDateTime | ZonedDateTime;
+/**
+ * Extracts time fields from a date range selection.
+ * @param selectedDate - The selected date range.
+ * @returns An object containing the start and end time fields.
+ */
+export declare function extractTimeFieldsFromDateRange(selectedDate: DateRangeSelection | null): RangeTimeFields;
+/**
+ * Extracts time fields from a single date selection.
+ * @param selectedDate - The selected date.
+ * @returns The time fields of the selected date, if available.
+ */
+export declare function extractTimeFieldsFromDate(selectedDate: SingleDateSelection | null): TimeFields | undefined;

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

@@ -1,66 +1,24 @@
-import { type ChangeEvent, type SyntheticEvent } from "react";
-import { type DateValue } from "@internationalized/date";
-import { type CalendarProps, type RangeSelectionValueType, type SingleSelectionValueType } from "../calendar";
-import { type DateInputProps } from "../date-input";
-export interface DatePickerProps<SelectionVariantType> extends DateInputProps<SelectionVariantType> {
-    /**
-     * Selection variant. Defaults to single select.
-     */
-    selectionVariant?: "default" | "range";
-    /**
-     * If `true`, the component will be disabled.
-     */
-    disabled?: boolean;
-    /**
-     * The selected date value. Use when the component is controlled.
-     * Can be a single date or an object with start and end dates for range selection.
-     */
-    selectedDate?: SelectionVariantType;
-    /**
-     * The default date value. Use when the component is not controlled.
-     * Can be a single date or an object with start and end dates for range selection.
-     */
-    defaultSelectedDate?: SelectionVariantType;
-    /**
-     * Props to be passed to the Calendar component.
-     */
-    CalendarProps?: Partial<Omit<CalendarProps, "selectionVariant" | "selectedDate" | "defaultSelectedDate" | "onSelectedDateChange">>;
-    /**
-     * Function to format the input value.
-     */
-    dateFormatter?: (input: DateValue | undefined) => string;
-    /**
-     * Callback function triggered when open state changes.
-     */
-    onOpenChange?: (newOpen: boolean) => void;
-    /**
-     * Display or hide the component.
-     */
+import { type ReactNode } from "react";
+import { type UseDatePickerRangeProps, type UseDatePickerSingleProps } from "./useDatePicker";
+/**
+ * Base props for DatePicker.
+ */
+export interface DatePickerBaseProps {
+    className?: string;
+    children?: ReactNode;
+    /** the open/close state of the overlay. The open/close state will be controlled when this prop is provided. */
     open?: boolean;
     /**
-     * The default open value. Use when the component is not controlled.
-     */
-    defaultOpen?: boolean;
-    /**
-     * Helper text to display in the panel
-     */
-    helperText?: string;
-    /**
-     * Validation status.
-     */
-    validationStatus?: "error" | "warning" | "success";
-    /**
-     * Callback fired when the selected date change.
-     */
-    onSelectionChange?: (event: SyntheticEvent, selectedDate?: SelectionVariantType) => void;
-    /**
-     * Callback fired when the input value change.
+     * the initial open/close state of the overlay, when the open/close state is un-controlled.
      */
-    onChange?: SelectionVariantType extends SingleSelectionValueType ? (event: ChangeEvent<HTMLInputElement>, selectedDateInputValue?: string) => void : (event: ChangeEvent<HTMLInputElement>, startDateInputValue?: string, endDateInputValue?: string) => void;
-    /**
-     * Number of Calendars to be shown if selectionVariant is range.
-     * 2 is the default value.
-     */
-    visibleMonths?: 1 | 2;
+    defaultOpen?: DatePickerBaseProps["open"];
+}
+export interface DatePickerSingleProps extends DatePickerBaseProps, UseDatePickerSingleProps {
+    selectionVariant: "single";
+}
+export interface DatePickerRangeProps extends DatePickerBaseProps, UseDatePickerRangeProps {
+    selectionVariant: "range";
 }
-export declare const DatePicker: import("react").ForwardRefExoticComponent<DatePickerProps<DateValue | RangeSelectionValueType> & import("react").RefAttributes<HTMLDivElement>>;
+export declare type DatePickerProps = DatePickerSingleProps | DatePickerRangeProps;
+export declare const DatePickerMain: import("react").ForwardRefExoticComponent<DatePickerProps & import("react").RefAttributes<HTMLDivElement>>;
+export declare const DatePicker: import("react").ForwardRefExoticComponent<DatePickerProps & import("react").RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,80 @@
+import { type ButtonProps } from "@salt-ds/core";
+import React, { type ComponentPropsWithoutRef, type SyntheticEvent, type Ref } from "react";
+import type { DateRangeSelection, SingleDateSelection } from "../calendar";
+import "./DatePickerActions.css";
+/**
+ * Base props for DatePicker actions.
+ */
+export interface DatePickerActionsBaseProps extends ComponentPropsWithoutRef<"div"> {
+    /**
+     * Callback fired when the cancel action is triggered.
+     * @param _event - The synthetic event.
+     */
+    onCancel?: (_event: SyntheticEvent) => void;
+    /**
+     * Ref to apply button
+     */
+    applyButtonRef?: Ref<HTMLButtonElement>;
+    /**
+     * Props for the apply button.
+     */
+    ApplyButtonProps?: ButtonProps;
+    /**
+     * Props for the cancel button.
+     */
+    CancelButtonProps?: ButtonProps;
+    /**
+     * Ref to cancel button
+     */
+    cancelButtonRef?: Ref<HTMLButtonElement>;
+}
+/**
+ * Props for the DatePicker actions component.
+ * @template SelectionVariant - The selection variant, either "single" or "range".
+ */
+export declare type DatePickerActionsProps<SelectionVariant extends "single" | "range"> = SelectionVariant extends "single" ? DatePickerActionsBaseProps & {
+    /**
+     * The selection variant, set to "single".
+     */
+    selectionVariant: "single";
+    /**
+     * Callback fired when the apply action is triggered.
+     * @param _event - The synthetic event.
+     * @param date - The selected single date or null.
+     */
+    onApply?: (_event: SyntheticEvent, date: SingleDateSelection | null) => void;
+} : DatePickerActionsBaseProps & {
+    /**
+     * The selection variant, set to "range".
+     */
+    selectionVariant: "range";
+    /**
+     * Callback fired when the apply action is triggered.
+     * @param _event - The synthetic event.
+     * @param date - The selected date range or null.
+     */
+    onApply?: (_event: SyntheticEvent, date: DateRangeSelection | null) => void;
+};
+export declare const DatePickerActions: React.ForwardRefExoticComponent<((DatePickerActionsBaseProps & {
+    /**
+     * The selection variant, set to "single".
+     */
+    selectionVariant: "single";
+    /**
+     * Callback fired when the apply action is triggered.
+     * @param _event - The synthetic event.
+     * @param date - The selected single date or null.
+     */
+    onApply?: ((_event: SyntheticEvent, date: SingleDateSelection | null) => void) | undefined;
+}) | (DatePickerActionsBaseProps & {
+    /**
+     * The selection variant, set to "range".
+     */
+    selectionVariant: "range";
+    /**
+     * Callback fired when the apply action is triggered.
+     * @param _event - The synthetic event.
+     * @param date - The selected date range or null.
+     */
+    onApply?: ((_event: SyntheticEvent, date: DateRangeSelection | null) => void) | undefined;
+})) & React.RefAttributes<HTMLDivElement>>;

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

@@ -1,19 +1,182 @@
 import type { DateValue } from "@internationalized/date";
-import { type UseFloatingUIReturn } from "@salt-ds/core";
-import type { RangeSelectionValueType } from "../calendar";
-export interface DatePickerContextValue<SelectionVariantType> extends Partial<Pick<UseFloatingUIReturn, "context">> {
-    openState: boolean;
-    setOpen: (newOpen: boolean) => void;
-    disabled: boolean;
-    selectedDate: SelectionVariantType | undefined;
-    defaultSelectedDate: SelectionVariantType | undefined;
-    setSelectedDate: (newStartDate: SelectionVariantType | undefined) => void;
-    startVisibleMonth: DateValue | undefined;
-    setStartVisibleMonth: (newStartDate: DateValue | undefined) => void;
-    endVisibleMonth: DateValue | undefined;
-    setEndVisibleMonth: (newStartDate: DateValue | undefined) => void;
-    selectionVariant: "default" | "range";
-    getPanelPosition: () => Record<string, unknown>;
+import type { DateRangeSelection, SingleDateSelection } from "../calendar";
+import type { DateInputRangeError, DateInputSingleError } from "../date-input";
+/**
+ * Interface representing the base state for a DatePicker.
+ */
+interface DatePickerBaseState {
+    /**
+     * The state properties of the DatePicker.
+     */
+    state: {
+        /**
+         * If `true`, the DatePicker is disabled.
+         */
+        disabled?: boolean;
+        /**
+         * If `true`, the DatePicker is read-only.
+         */
+        readOnly?: boolean;
+        /**
+         * If `true`, the DatePicker has been cancelled.
+         */
+        cancelled?: boolean;
+        /**
+         * If `true`, the apply action is enabled.
+         */
+        enableApply?: boolean;
+        /**
+         * The minimum selectable date.
+         */
+        minDate?: DateValue;
+        /**
+         * The maximum selectable date.
+         */
+        maxDate?: DateValue;
+        /**
+         * Reference to the container element.
+         */
+        containerRef: React.Ref<HTMLDivElement>;
+        /**
+         * The locale used for date formatting.
+         */
+        locale?: string;
+        /**
+         * The time zone used for date formatting.
+         */
+        timeZone?: string;
+    };
+    /**
+     * Helper functions for managing the DatePicker state.
+     */
+    helpers: {
+        /**
+         * Cancels the DatePicker action.
+         */
+        cancel: () => void;
+        /**
+         * Sets the enableApply state.
+         * @param newEnableApply - The new value for enableApply.
+         */
+        setEnableApply: (newEnableApply: boolean) => void;
+    };
 }
-export declare const DatePickerContext: import("react").Context<DatePickerContextValue<DateValue | RangeSelectionValueType>>;
-export declare function useDatePickerContext(): DatePickerContextValue<DateValue | RangeSelectionValueType>;
+/**
+ * Type representing a single date picker error.
+ */
+export declare type SingleDatePickerError = DateInputSingleError;
+/**
+ * Type representing a range date picker error.
+ */
+export declare type RangeDatePickerError = DateInputRangeError;
+/**
+ * Interface representing the state for a single date picker.
+ */
+export interface SingleDatePickerState extends DatePickerBaseState {
+    /**
+     * The state properties of the single date picker.
+     */
+    state: DatePickerBaseState["state"] & {
+        /**
+         * The selected date.
+         */
+        selectedDate: SingleDateSelection | null;
+        /**
+         * The default selected date.
+         */
+        defaultSelectedDate?: SingleDateSelection;
+    };
+    /**
+     * Helper functions for managing the single date picker state.
+     */
+    helpers: DatePickerBaseState["helpers"] & {
+        /**
+         * Applies the selected date.
+         * @param newDate - The new selected date.
+         * @param error - The error encountered during selection, if any.
+         */
+        apply: (newDate: SingleDateSelection | null, error: SingleDatePickerError) => void;
+        /**
+         * Sets the selected date.
+         * @param newDate - The new selected date.
+         * @param error - The error encountered during selection, if any.
+         */
+        setSelectedDate: (newDate: SingleDateSelection | null, error: string | false) => void;
+    };
+}
+/**
+ * Interface representing the state for a range date picker.
+ */
+export interface RangeDatePickerState extends DatePickerBaseState {
+    /**
+     * The state properties of the range date picker.
+     */
+    state: DatePickerBaseState["state"] & {
+        /**
+         * The selected date range.
+         */
+        selectedDate: DateRangeSelection | null;
+        /**
+         * The default selected date range.
+         */
+        defaultSelectedDate?: DateRangeSelection;
+    };
+    /**
+     * Helper functions for managing the range date picker state.
+     */
+    helpers: DatePickerBaseState["helpers"] & {
+        /**
+         * Applies the selected date range.
+         * @param newDate - The new selected date range.
+         * @param error - The error encountered during selection, if any.
+         */
+        apply: (newDate: DateRangeSelection | null, error: RangeDatePickerError) => void;
+        /**
+         * Sets the selected date range.
+         * @param newDate - The new selected date range.
+         * @param error - The error encountered during selection, if any.
+         */
+        setSelectedDate: (newDate: DateRangeSelection | null, error: {
+            startDate: string | false;
+            endDate: string | false;
+        }) => void;
+    };
+}
+/**
+ * Type representing the state of a date picker, either single or range.
+ */
+export declare type DatePickerState = SingleDatePickerState | RangeDatePickerState;
+/**
+ * Context for single date selection.
+ */
+export declare const SingleDateSelectionContext: import("react").Context<SingleDatePickerState | undefined>;
+/**
+ * Context for date range selection.
+ */
+export declare const DateRangeSelectionContext: import("react").Context<RangeDatePickerState | undefined>;
+/**
+ * Props for using the date picker context.
+ */
+export interface UseDatePickerContextProps {
+    /**
+     * The selection variant, either "single" or "range".
+     */
+    selectionVariant: "single" | "range";
+}
+/**
+ * Hook to use the date picker context for single date selection.
+ * @param props - The props for the hook.
+ * @returns The state of the single date picker.
+ */
+export declare function useDatePickerContext(props: {
+    selectionVariant: "single";
+}): SingleDatePickerState;
+/**
+ * Hook to use the date picker context for range date selection.
+ * @param props - The props for the hook.
+ * @returns The state of the range date picker.
+ */
+export declare function useDatePickerContext(props: {
+    selectionVariant: "range";
+}): RangeDatePickerState;
+export {};