@pushwoosh/dumb-components 1.1.148 → 1.1.149

package/AccessForbidden/AccessForbidden.d.ts

@@ -1,2 +1,5 @@
 import { type ReactElement } from 'react';
+/**
+ * Full-page "access forbidden" state with an illustration and localized title/description.
+ */
 export declare function AccessForbidden(): ReactElement;

package/AccessForbidden/AccessForbidden.js

@@ -2,6 +2,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import accessForbiddenImage from './assets/AccessForbidden.svg?url';
 import { Lang, useLang } from './polyglot';
 import { RootBox, ImageBox, TitleBox, DescriptionBox } from './styles';
+/**
+ * Full-page "access forbidden" state with an illustration and localized title/description.
+ */
 export function AccessForbidden() {
   const lang = useLang();
   return _jsxs(RootBox, {

package/Alert/Alert.d.ts

@@ -1,2 +1,9 @@
 import type { AlertProps } from './types';
+/**
+ * Inline message banner with info/warning/error styling; collapses into an
+ * accordion when given `children`.
+ *
+ * @example
+ * <Alert type="warning" title="Heads up">Details about the warning.</Alert>
+ */
 export declare const Alert: ({ isExpandedDefault, title, type, children }: AlertProps) => import("react/jsx-runtime").JSX.Element;

package/Alert/Alert.js

@@ -5,6 +5,13 @@ import { Horizontal, Vertical } from '@pushwoosh/kit-helpers';
 import { ChevronIcon } from '@pushwoosh/kit-icons';
 import { AlertTypeMap } from './maps';
 import { AccordionHeader, Container } from './styles';
+/**
+ * Inline message banner with info/warning/error styling; collapses into an
+ * accordion when given `children`.
+ *
+ * @example
+ * <Alert type="warning" title="Heads up">Details about the warning.</Alert>
+ */
 export const Alert = ({
   isExpandedDefault,
   title,

package/Alert/types.d.ts

@@ -1,8 +1,14 @@
 import type { ReactNode } from 'react';
+/** Severity of an {@link Alert}, driving its icon and colors. */
 export type AlertType = 'info' | 'warning' | 'error';
+/** Props of {@link Alert}. */
 export type AlertProps = {
+    /** Always-visible header content. */
     title: ReactNode;
+    /** Severity — sets the icon and background color. */
     type: AlertType;
+    /** Start expanded (only relevant when `children` are provided). */
     isExpandedDefault?: boolean;
+    /** Collapsible body; when present the alert becomes an accordion. */
     readonly children?: ReactNode;
 };

package/ApplicationPreloader/ApplicationPreloader.d.ts

@@ -1,4 +1,12 @@
+/** Props of {@link ApplicationPreloader}. */
 export type ApplicationPreloaderProps = {
+    /** Fill the viewport (default `true`); when `false` fills the parent. */
     fullscreen?: boolean;
 };
+/**
+ * Branded loading animation shown while the app boots; fullscreen by default.
+ *
+ * @example
+ * <ApplicationPreloader />
+ */
 export declare function ApplicationPreloader({ fullscreen }: ApplicationPreloaderProps): import("react/jsx-runtime").JSX.Element;

package/ApplicationPreloader/ApplicationPreloader.js

@@ -1,5 +1,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { ApplicationPreloaderBox, ApplicationPreloaderAnimation } from './styles';
+/**
+ * Branded loading animation shown while the app boots; fullscreen by default.
+ *
+ * @example
+ * <ApplicationPreloader />
+ */
 export function ApplicationPreloader({
   fullscreen = true
 }) {

package/Badge/Badge.d.ts

@@ -1,3 +1,9 @@
 import { type ReactElement } from 'react';
 import type { BadgeProps } from './types';
+/**
+ * Small colored label for statuses and counts.
+ *
+ * @example
+ * <Badge color="green">Active</Badge>
+ */
 export declare function Badge(props: BadgeProps): ReactElement;

package/Badge/Badge.js

@@ -1,5 +1,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { BadgeBox } from './styles';
+/**
+ * Small colored label for statuses and counts.
+ *
+ * @example
+ * <Badge color="green">Active</Badge>
+ */
 export function Badge(props) {
   const {
     boxRef,

package/Badge/types.d.ts

@@ -1,8 +1,14 @@
 import type { Ref, ReactNode } from 'react';
+/** Color of a {@link Badge}. */
 export type BadgeColor = 'gray' | 'green' | 'orange' | 'red' | 'purple' | 'sky' | 'locked' | 'black';
+/** Props of {@link Badge} — all `<div>` attributes plus the badge-specific ones. */
 export type BadgeProps = Omit<JSX.IntrinsicElements['div'], 'ref'> & {
+    /** Ref to the badge `<div>`. */
     readonly boxRef?: Ref<HTMLDivElement>;
+    /** Badge color. */
     readonly color: BadgeColor;
+    /** Use the saturated (solid) variant instead of the tinted one. */
     readonly isSaturated?: boolean;
+    /** Badge content. */
     readonly children: ReactNode;
 };

package/Banner/Banner.d.ts

@@ -1,3 +1,10 @@
 import { type ReactElement } from 'react';
 import type { BannerPropsWithButton, RequiredBannerProps } from './types';
+/**
+ * Prominent page-level message with severity styling, an optional action button,
+ * a loading state and a dismiss button. Hides itself once closed.
+ *
+ * @example
+ * <Banner type="success" title="Saved" canBeClosed action={{ buttonText: 'Undo', onClick: undo }} />
+ */
 export declare function Banner(props: RequiredBannerProps | BannerPropsWithButton): ReactElement | null;

package/Banner/Banner.js

@@ -6,6 +6,13 @@ import { H4 } from '@pushwoosh/kit-typography';
 import { Spinner } from '../Spinner';
 import { BannerPropsToBannerBoxMap, BannerPropsToIconContainerMap, BannerTypeToSpinnerColorMap } from './maps';
 import { ActionButton, BannerContent, BannerSpinner, CloseButton, IconContainer } from './styles';
+/**
+ * Prominent page-level message with severity styling, an optional action button,
+ * a loading state and a dismiss button. Hides itself once closed.
+ *
+ * @example
+ * <Banner type="success" title="Saved" canBeClosed action={{ buttonText: 'Undo', onClick: undo }} />
+ */
 export function Banner(props) {
   const [isOpen, setIsOpen] = useState(true);
   const [isActionPressed, setIsActionPressed] = useState(false);

package/Banner/types.d.ts

@@ -1,20 +1,36 @@
 import type { ReactElement, ReactNode } from 'react';
+/** Severity of a {@link Banner}, driving its icon and colors. */
 export type BannerType = 'error' | 'warning' | 'info' | 'success';
+/** Base props of {@link Banner}. */
 export type RequiredBannerProps = {
+    /** Ref to the banner root element. */
     readonly boxRef?: any;
+    /** Severity — sets the default icon and colors. */
     readonly type: BannerType;
+    /** Banner heading. */
     readonly title: string;
+    /** Surface style: `shape` (filled, default) or `ghost`. */
     readonly view?: 'shape' | 'ghost';
+    /** Custom icon; falls back to the type's default icon. */
     readonly icon?: ReactElement;
+    /** Extra CSS class on the banner root. */
     readonly className?: string;
+    /** Show the loading state on the action button. */
     readonly isLoading?: boolean;
+    /** Show a close (✕) button. */
     readonly canBeClosed?: boolean;
+    /** Fires when the close button is clicked. */
     readonly onClose?: () => void;
+    /** Body content under the title. */
     readonly children?: ReactNode;
 };
+/** {@link Banner} props with an optional action button. */
 export type BannerPropsWithButton = RequiredBannerProps & {
+    /** Action button shown on the right. */
     readonly action?: {
+        /** Fires when the action button is clicked. */
         readonly onClick: () => void;
+        /** Action button caption. */
         readonly buttonText: string;
     };
 };

package/Button/Button.d.ts

@@ -1,5 +1,24 @@
 import { type ReactElement } from 'react';
 import type { ButtonPropsWithoutAs, ButtonPropsWithAsTag, ButtonPropsWithAsComponent } from './types';
+/**
+ * Primary action button with color/size/view variants, icons and a loading state.
+ * Renders a native `<button>`.
+ *
+ * @example
+ * <Button color="primary" isLoading={saving} onClick={save}>Save</Button>
+ */
 export declare function Button(props: ButtonPropsWithoutAs): ReactElement | null;
+/**
+ * Button rendered as another intrinsic tag via `as` (keeping the button styling).
+ *
+ * @example
+ * <Button as="a" href="/docs" color="secondary">Docs</Button>
+ */
 export declare function Button<AS extends keyof HTMLElementTagNameMap>(props: ButtonPropsWithAsTag<AS>): ReactElement | null;
+/**
+ * Button rendered as a custom component via `as` (e.g. a router link).
+ *
+ * @example
+ * <Button as={RouterLink} to="/home" color="primary">Home</Button>
+ */
 export declare function Button<OuterProps extends object>(props: ButtonPropsWithAsComponent<OuterProps>): ReactElement | null;

package/Button/GhostButton.d.ts

@@ -1 +1,2 @@
+/** Unstyled, transparent `<button>` reset — no padding, border or background; use for icon/inline triggers. */
 export declare const GhostButton: import("styled-components").StyledComponent<"button", any, {}, never>;

package/Button/GhostButton.js

@@ -1,4 +1,5 @@
 import styled from 'styled-components';
+/** Unstyled, transparent `<button>` reset — no padding, border or background; use for icon/inline triggers. */
 export const GhostButton = styled.button.withConfig({
   displayName: "GhostButton",
   componentId: "sc-11te6l1-0"

package/Button/RemoveButton.d.ts

@@ -1,2 +1,8 @@
 import { type JSX, type ReactElement } from 'react';
+/**
+ * Small round button with a close (✕) icon, for removing/dismissing an item.
+ *
+ * @example
+ * <RemoveButton aria-label="Remove" onClick={remove} />
+ */
 export declare function RemoveButton(props: Omit<JSX.IntrinsicElements['button'], 'ref' | 'children'>): ReactElement;

package/Button/RemoveButton.js

@@ -1,6 +1,12 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { CloseIcon } from '@pushwoosh/kit-icons';
 import { RemoveButtonBox } from './styles';
+/**
+ * Small round button with a close (✕) icon, for removing/dismissing an item.
+ *
+ * @example
+ * <RemoveButton aria-label="Remove" onClick={remove} />
+ */
 export function RemoveButton(props) {
   return _jsx(RemoveButtonBox, {
     ...props,

package/Button/types.d.ts

@@ -1,26 +1,47 @@
 import type { JSX, ReactNode, Ref, ComponentType } from 'react';
+/** Props shared by every {@link Button} variant, regardless of the rendered element. */
 export type RequiredButtonProps = {
+    /** Ref forwarded to the underlying element; prefer the typed `boxRef` on the variant props. */
     readonly boxRef?: any;
+    /** Visual intent: `primary` (main action), `secondary` (neutral), `danger` (destructive). */
     readonly color: 'primary' | 'secondary' | 'danger';
+    /** Height preset: `field` (default, form-line height) or `compact` (denser). */
     readonly size?: 'field' | 'compact';
+    /** Surface style: `shape` (filled, default) or `ghost` (transparent). */
     readonly view?: 'shape' | 'ghost';
+    /** Extra CSS class applied to the button element. */
     readonly className?: string;
+    /** Disable interaction and render the disabled state. */
     readonly isDisabled?: boolean;
+    /** Show a spinner (in place of the left icon, or overlaid on the label). */
     readonly isLoading?: boolean;
+    /** Mark the button as expanded/active, e.g. when it toggles a dropdown. */
     readonly isOpen?: boolean;
+    /** Icon rendered before the label. */
     readonly icon?: ReactNode;
+    /** Icon rendered after the label. */
     readonly rightIcon?: ReactNode;
+    /** Button label. */
     readonly children?: ReactNode;
 };
+/** Default {@link Button} props — renders a native `<button>`. */
 export type ButtonPropsWithoutAs = Omit<JSX.IntrinsicElements['button'], 'ref'> & RequiredButtonProps & {
+    /** Ref to the underlying `<button>` element. */
     readonly boxRef?: Ref<HTMLButtonElement>;
+    /** Native button type. */
     readonly type?: 'button' | 'submit';
 };
+/** {@link Button} props when rendering as another intrinsic HTML tag via `as` (e.g. `as="a"`). */
 export type ButtonPropsWithAsTag<AS extends keyof HTMLElementTagNameMap> = Omit<JSX.IntrinsicElements[AS], 'ref'> & RequiredButtonProps & {
+    /** Ref to the element produced by `as`. */
     readonly boxRef?: Ref<HTMLElementTagNameMap[AS]>;
+    /** Intrinsic tag name to render instead of `<button>`. */
     readonly as?: AS;
 };
+/** {@link Button} props when rendering as a custom component via `as` (e.g. a router `Link`). */
 export type ButtonPropsWithAsComponent<OuterProps extends object> = OuterProps & RequiredButtonProps & {
+    /** Ref to the rendered component's root element. */
     readonly boxRef?: Ref<HTMLElement>;
+    /** Custom component to render instead of `<button>`; receives `OuterProps`. */
     readonly as?: ComponentType<OuterProps>;
 };

package/Calendar/CalendarDropdown/CalendarDropdown.d.ts

@@ -1,3 +1,15 @@
 import { type FC } from 'react';
 import { type CalendarDropdownProps } from './types';
+/**
+ * Button that opens a {@link CalendarSuperForm} in a popover, formats the selection on
+ * the button, supports range presets and commits via `onSubmit`.
+ *
+ * @example
+ * <CalendarDropdown
+ *   mode="range-date"
+ *   calendarProps={{}}
+ *   value={range}
+ *   onSubmit={(value, tz) => save(value, tz)}
+ * />
+ */
 export declare const CalendarDropdown: FC<CalendarDropdownProps>;

package/Calendar/CalendarDropdown/CalendarDropdown.js

@@ -12,6 +12,18 @@ import { Chip } from '../../Chip';
 import { useLayer, useOnClickOutside } from '../../hooks';
 import { CalendarSuperForm } from '../CalendarSuperForm';
 import { Lang, useLang } from '../polyglot';
+/**
+ * Button that opens a {@link CalendarSuperForm} in a popover, formats the selection on
+ * the button, supports range presets and commits via `onSubmit`.
+ *
+ * @example
+ * <CalendarDropdown
+ *   mode="range-date"
+ *   calendarProps={{}}
+ *   value={range}
+ *   onSubmit={(value, tz) => save(value, tz)}
+ * />
+ */
 export const CalendarDropdown = props => {
   const {
     mode,

package/Calendar/CalendarDropdown/helpers.d.ts

@@ -1,3 +1,7 @@
 import { type DateStruct, type DateTimeStruct, type RangeValue, type SingleValue } from '../types';
 export declare function formatDate(val: DateStruct | DateTimeStruct, withTime?: boolean): string;
+/**
+ * Formats a single value or range for display in the {@link CalendarDropdown} button:
+ * `"Jan 01, 2026"`, `"Jan 01, 2026 – Jan 05, 2026"`, with time and a short timezone when `withTime`.
+ */
 export declare const stringifyValue: (value: SingleValue<DateStruct | DateTimeStruct> | RangeValue<DateStruct | DateTimeStruct>, withTime: boolean, timezone?: string) => string;

package/Calendar/CalendarDropdown/helpers.js

@@ -17,6 +17,10 @@ export function formatDate(val, withTime = true) {
     year: 'numeric'
   });
 }
+/**
+ * Formats a single value or range for display in the {@link CalendarDropdown} button:
+ * `"Jan 01, 2026"`, `"Jan 01, 2026 – Jan 05, 2026"`, with time and a short timezone when `withTime`.
+ */
 export const stringifyValue = (value, withTime, timezone) => {
   let result = '';
   if (Array.isArray(value)) {

package/Calendar/CalendarDropdown/types.d.ts

@@ -2,48 +2,81 @@ import { type ReactNode } from 'react';
 import { type RequiredButtonProps } from '../../Button';
 import type { CalendarRangeDateProps, CalendarRangeDateTimeProps, CalendarSingleDateProps, CalendarSingleDateTimeProps } from '../CalendarSuperForm/types';
 import type { DateStruct, DateTimeStruct, RangeValue, TzValue } from '../types';
+/** Props shared by every {@link CalendarDropdown} mode (the trigger button + commit behaviour). */
 interface BaseProps {
+    /** Trigger button size. */
     buttonSize?: RequiredButtonProps['size'];
+    /** Trigger button color (default `secondary`). */
     buttonColor?: RequiredButtonProps['color'];
+    /** Trigger button view. */
     buttonView?: RequiredButtonProps['view'];
+    /** Override the button label instead of the formatted value. */
     buttonTextCustom?: string;
+    /** Allow submitting with no value selected. */
     allowEmpty?: boolean;
 }
+/** {@link CalendarDropdown} props for picking a single date. */
 export interface CalendarDropdownSingleDateProps extends BaseProps {
+    /** Single date-only mode. */
     mode: 'single-date';
+    /** Props forwarded to the inner {@link CalendarSuperForm} (minus mode/value/onChange). */
     calendarProps: Omit<CalendarSingleDateProps, 'mode' | 'value' | 'onChange'>;
+    /** Currently selected date. */
     value?: DateStruct;
+    /** Fires on every in-popover change (before commit). */
     onChange?: (value: DateStruct) => void;
+    /** Fires with the committed date and timezone when the user applies the selection. */
     onSubmit: (value: DateStruct, tz: TzValue) => void;
 }
+/** {@link CalendarDropdown} props for picking a single date and time. */
 export interface CalendarDropdownSingleDateTimeProps extends BaseProps {
+    /** Single date-time mode. */
     mode: 'single-datetime';
+    /** Props forwarded to the inner {@link CalendarSuperForm} (minus mode/value/onChange). */
     calendarProps: Omit<CalendarSingleDateTimeProps, 'mode' | 'value' | 'onChange'>;
+    /** Currently selected date-time. */
     value?: DateTimeStruct;
+    /** Fires on every in-popover change (before commit). */
     onChange?: (value: DateTimeStruct) => void;
+    /** Fires with the committed date-time and timezone when applied. */
     onSubmit: (value: DateTimeStruct, tz: TzValue) => void;
 }
+/** {@link CalendarDropdown} props for picking a date range, with optional presets. */
 export interface CalendarDropdownRangeDateProps extends BaseProps {
+    /** Date range mode. */
     mode: 'range-date';
+    /** Props forwarded to the inner {@link CalendarSuperForm} (minus mode/value/onChange). */
     calendarProps: Omit<CalendarRangeDateProps, 'mode' | 'value' | 'onChange'>;
+    /** Currently selected range. */
     value?: RangeValue<DateStruct>;
+    /** Fires on every in-popover change (before commit). */
     onChange?: (value: RangeValue<DateStruct>) => void;
+    /** Fires with the committed range and timezone when applied. */
     onSubmit: (value: RangeValue<DateStruct>, tz: TzValue) => void;
+    /** Quick-pick presets shown beside the calendar. */
     presets?: Array<{
         label: ReactNode | string;
         value: [DateStruct, DateStruct];
     }>;
 }
+/** {@link CalendarDropdown} props for picking a date-time range, with optional presets. */
 export interface CalendarDropdownRangeDateTimeProps extends BaseProps {
+    /** Date-time range mode. */
     mode: 'range-datetime';
+    /** Props forwarded to the inner {@link CalendarSuperForm} (minus mode/value/onChange). */
     calendarProps: Omit<CalendarRangeDateTimeProps, 'mode' | 'value' | 'onChange'>;
+    /** Currently selected range. */
     value?: RangeValue<DateTimeStruct>;
+    /** Fires on every in-popover change (before commit). */
     onChange?: (value: RangeValue<DateTimeStruct>) => void;
+    /** Fires with the committed range and timezone when applied. */
     onSubmit: (value: RangeValue<DateTimeStruct>, tz: TzValue) => void;
+    /** Quick-pick presets shown beside the calendar. */
     presets?: Array<{
         label: ReactNode | string;
         value: [DateTimeStruct, DateTimeStruct];
     }>;
 }
+/** Props of {@link CalendarDropdown} — a discriminated union keyed by `mode`. */
 export type CalendarDropdownProps = CalendarDropdownSingleDateProps | CalendarDropdownSingleDateTimeProps | CalendarDropdownRangeDateProps | CalendarDropdownRangeDateTimeProps;
 export {};

package/Calendar/CalendarSuperForm/CalendarSuperForm.d.ts

@@ -1,3 +1,10 @@
 import { type FC } from 'react';
 import { type CalendarSuperFormProps } from './types';
+/**
+ * Inline calendar form supporting single/range and date/date-time selection via `mode`,
+ * with optional timezone, day-count limits and a custom footer.
+ *
+ * @example
+ * <CalendarSuperForm mode="range-date" value={range} onChange={setRange} />
+ */
 export declare const CalendarSuperForm: FC<CalendarSuperFormProps>;

package/Calendar/CalendarSuperForm/CalendarSuperForm.js

@@ -4,6 +4,13 @@ import { Vertical } from '@pushwoosh/kit-helpers';
 import { Text } from '@pushwoosh/kit-typography';
 import { CalendarRangePicker } from './components/CalendarRangePicker/CalendarRangePicker';
 import { CalendarTimeAndTimezoneSection } from './components/CalendarTimeAndTimezoneSection/CalendarTimeAndTimezoneSection';
+/**
+ * Inline calendar form supporting single/range and date/date-time selection via `mode`,
+ * with optional timezone, day-count limits and a custom footer.
+ *
+ * @example
+ * <CalendarSuperForm mode="range-date" value={range} onChange={setRange} />
+ */
 export const CalendarSuperForm = props => {
   const {
     mode,

package/Calendar/CalendarSuperForm/types.d.ts

@@ -1,61 +1,87 @@
 import { type ReactNode } from 'react';
 import { type DateStruct, type DateTimeStruct, type RangeValue, type SingleValue, type TzValue } from '../types';
+/** Props shared by every {@link CalendarSuperForm} mode. */
 interface BaseProps {
-    /** Количество видимых месяцев. */
+    /** Number of months shown side by side. */
     visibleCount?: number;
-    /** Ширина одного месяца. */
+    /** Width of a single month grid, in pixels. */
     monthWidth?: number;
-    /** Промежуток между месяцами. */
+    /** Gap between months, in pixels. */
     gap?: number;
-    /** Отключить даты до этой (включительно). */
+    /** Disable all dates on and before this date (inclusive). */
     disableOnAndBefore?: DateStruct;
-    /** Отключить даты после этой (включительно). */
+    /** Disable all dates on and after this date (inclusive). */
     disableOnAndAfter?: DateStruct;
-    /** Первый день недели: 0 - воскресенье, 1 - понедельник. По умолчанию 0. */
+    /** First day of the week: `0` = Sunday, `1` = Monday (default `0`). */
     firstDayOfWeek?: 0 | 1;
-    /** Месяц, на котором календарь открывается изначально. По умолчанию — начало диапазона (value[0]) либо текущий месяц. */
+    /** Month the calendar opens on; defaults to the range start (`value[0]`) or the current month. */
     initialVisibleMonth?: DateStruct;
-    /** Кастомный футер-аннотация, который рендерится после календаря и после min/max days limitation. */
+    /** Custom footer node rendered below the calendar and the min/max-days notice. */
     footerContent?: ReactNode;
 }
+/** Selection mode of {@link CalendarSuperForm}: single vs range, date-only vs date-time. */
 export type CalendarMode = 'single-date' | 'single-datetime' | 'range-date' | 'range-datetime';
+/** {@link CalendarSuperForm} props for picking a single date (no time, no timezone). */
 export interface CalendarSingleDateProps extends BaseProps {
+    /** Single date-only mode. */
     mode: 'single-date';
-    /** Временная зона не нужна и запрещена */
+    /** Not used and disallowed in this mode. */
     timezone?: never;
     onChangeTimezone?: never;
     minDays?: never;
     maxDays?: never;
+    /** Currently selected date. */
     value?: SingleValue<DateStruct>;
+    /** Fires with the newly selected date. */
     onChange: (value: SingleValue<DateStruct>) => void;
 }
+/** {@link CalendarSuperForm} props for picking a single date and time in a timezone. */
 export interface CalendarSingleDateTimeProps extends BaseProps {
+    /** Single date-time mode. */
     mode: 'single-datetime';
-    /** Требуется, IANA-название таймзоны (напр., 'America/New_York') */
+    /** Required IANA timezone name (e.g. `'America/New_York'`). */
     timezone: TzValue;
+    /** Fires when the timezone changes. */
     onChangeTimezone: (timezone: TzValue) => void;
     minDays?: never;
     maxDays?: never;
+    /** Currently selected date-time. */
     value?: SingleValue<DateTimeStruct>;
+    /** Fires with the newly selected date-time. */
     onChange: (payload: SingleValue<DateTimeStruct>) => void;
 }
+/** {@link CalendarSuperForm} props for picking a date range (no time, no timezone). */
 export interface CalendarRangeDateProps extends BaseProps {
+    /** Date range mode. */
     mode: 'range-date';
     timezone?: never;
     onChangeTimezone?: never;
+    /** Minimum allowed range length, in days. */
     minDays?: number;
+    /** Maximum allowed range length, in days. */
     maxDays?: number;
+    /** Currently selected range. */
     value: RangeValue<DateStruct>;
+    /** Fires with the newly selected range. */
     onChange: (value: RangeValue<DateStruct>) => void;
 }
+/** {@link CalendarSuperForm} props for picking a date-time range in a timezone. */
 export interface CalendarRangeDateTimeProps extends BaseProps {
+    /** Date-time range mode. */
     mode: 'range-datetime';
+    /** Required IANA timezone name. */
     timezone: TzValue;
+    /** Fires when the timezone changes. */
     onChangeTimezone: (timezone: TzValue) => void;
+    /** Minimum allowed range length, in days. */
     minDays?: number;
+    /** Maximum allowed range length, in days. */
     maxDays?: number;
+    /** Currently selected range. */
     value: RangeValue<DateTimeStruct>;
+    /** Fires with the newly selected range. */
     onChange: (payload: RangeValue<DateTimeStruct>) => void;
 }
+/** Props of {@link CalendarSuperForm} — a discriminated union keyed by `mode`. */
 export type CalendarSuperFormProps = CalendarSingleDateProps | CalendarSingleDateTimeProps | CalendarRangeDateProps | CalendarRangeDateTimeProps;
 export {};

package/Calendar/helpers.d.ts

@@ -6,20 +6,30 @@ export declare const createUTCDate: (year: number, month?: number, day?: number,
 export declare const parseStringToDate: (date: string) => Date;
 export declare const formatTwoDigitNumber: (value: number) => string;
 export declare const formatStruct: (ds: DateStruct, template: string) => string;
+/** Returns a new struct with `value` units of `period` added (negative to subtract); rolls over correctly. */
 export declare const addPeriod: <T extends DateTimeStruct | DateStruct>(ds: T, period: Period, value: number) => T;
+/** Narrows a {@link DateTimeStruct} to a date-only {@link DateStruct} (drops the time fields). */
 export declare const pickDateStruct: (date: DateTimeStruct) => DateStruct;
 export declare const setPeriodStruct: <T extends DateTimeStruct | DateStruct>(ds: T, period: Period, value: number) => T;
 export declare const extendPeriodStruct: (struct: DateTimeStruct, extend: Partial<DateTimeStruct>) => DateTimeStruct;
 export declare const differenceInDays: (ds1: DateStruct, ds2: DateStruct) => number;
 export declare const monthName: (month: number, monthFormat?: "short" | "long") => string;
 export declare const isSamePeriod: <T extends DateTimeStruct | DateStruct>(ds1: T, ds2: T, period: Period) => boolean;
+/** Compares two structs chronologically: `-1` if `ds1 < ds2`, `0` if equal, `1` if `ds1 > ds2`. */
 export declare const compareStructs: <T extends DateTimeStruct | DateStruct>(ds1: T, ds2: T) => 1 | 0 | -1;
 export declare const getFirstDayOfWeek: (date: DateStruct, firstDayOfWeek?: number) => DateStruct;
 export declare const getLastDayOfMonth: (date: DateStruct) => DateStruct;
+/** Returns the start of the given `period` containing `date` (e.g. first instant of the month). */
 export declare const getPeriodStart: (date: DateTimeStruct | DateStruct, period: Period) => DateTimeStruct;
+/** Returns the last instant of the given `period` containing `date` (e.g. 23:59:59.999 of the day). */
 export declare const getPeriodEnd: (date: DateTimeStruct | DateStruct, period: Period) => DateTimeStruct;
+/** Converts a `Date` to a {@link DateTimeStruct} shifted by `tzOffsetMinutes` (minutes east of UTC). */
 export declare const dateToStruct: (date: Date, tzOffsetMinutes: number) => DateTimeStruct;
+/** Converts a struct back to a `Date`, interpreting it as a wall-clock time `tzOffsetMinutes` east of UTC. */
 export declare const structToDate: (ds: DateTimeStruct | DateStruct, tzOffsetMinutes: number) => Date;
+/** Returns the offset in minutes (east of UTC) for an IANA `timezoneName` at the given instant `at`. */
 export declare function getTimezoneOffset(timezoneName: string, at?: Date): number;
+/** Like {@link dateToStruct} but resolves the offset from an IANA `tzName` (handles DST). */
 export declare const dateToStructTz: (date: Date, tzName: string) => DateTimeStruct;
+/** Like {@link structToDate} but resolves the offset from an IANA `tzName` (handles DST). */
 export declare const structToDateTz: (ds: DateTimeStruct | DateStruct, tzName: string) => Date;