@glob-ui/calendar 0.0.0-stage → 0.1.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# @glob-ui/calendar
 
-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.
+A month grid for picking one day or a range of days. Values are ISO date strings ("YYYY-MM-DD"), so they serialize and compare without time zones.
+
+## Install
+
+```bash
+pnpm add @glob-ui/calendar
+```
+
+## Documentation
+
+Full docs, examples and the accessibility table: [Calendar](https://github.com/kevin-martineze/GlobUI/tree/main/apps/docs/content/docs/components/calendar.mdx).
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/index.d.mts

@@ -0,0 +1,92 @@
+import * as react from 'react';
+
+interface DateRange {
+    from: string | null;
+    to: string | null;
+}
+interface CalendarBaseProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "defaultValue" | "onChange"> {
+    /** The first day of the week, 0 (Sunday) to 6. Default: from the locale. */
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    /**
+     * BCP 47 tag, for example "es-ES". Default: the browser's locale. Server-rendered pages show "en-US" until
+     * hydration, then switch; pass `locale` to avoid the switch.
+     */
+    locale?: string;
+    /** Earliest selectable day, "YYYY-MM-DD". Days before it are disabled and navigation stops before its month. */
+    min?: string;
+    /** Latest selectable day, "YYYY-MM-DD". Days after it are disabled and navigation stops after its month. */
+    max?: string;
+    /** Disables more days. Disabled days can still receive focus, but cannot be selected. */
+    isDateDisabled?: (iso: string) => boolean;
+    /** The visible month, "YYYY-MM" (controlled). */
+    month?: string;
+    defaultMonth?: string;
+    onMonthChange?: (month: string) => void;
+    /** Shows one month, or two side by side (stacked on small screens). */
+    numberOfMonths?: 1 | 2;
+    /** Muted days from the adjacent months. Not selectable; clicking one moves to its month. Default true. */
+    showOutsideDays?: boolean;
+    /** Called when the user picks an enabled day, even when it is already the selected one. Used by DatePicker to close. */
+    onSelectDay?: (iso: string) => void;
+}
+interface CalendarSingleProps extends CalendarBaseProps {
+    mode?: "single";
+    value?: string | null;
+    defaultValue?: string | null;
+    onChange?: (iso: string | null) => void;
+    /** Clicking the selected day again clears it. Default false. */
+    allowDeselect?: boolean;
+}
+interface CalendarRangeProps extends CalendarBaseProps {
+    mode: "range";
+    value?: DateRange;
+    defaultValue?: DateRange;
+    onChange?: (range: DateRange) => void;
+}
+type CalendarProps = CalendarSingleProps | CalendarRangeProps;
+/**
+ * A month grid for picking one day, or a range of days. Values are "YYYY-MM-DD" strings.
+ * Follows the WAI-ARIA date picker grid: one tab stop, arrows move by day and week, PageUp and PageDown by month.
+ */
+declare const Calendar: react.ForwardRefExoticComponent<CalendarProps & react.RefAttributes<HTMLDivElement>>;
+
+/** The local calendar date of `date` as "YYYY-MM-DD". */
+declare function toISODate(date: Date): string;
+/** Local midnight of an ISO date. */
+declare function parseISODate(iso: string): Date;
+/** The date `n` days after `iso` (negative goes back). */
+declare function addDays(iso: string, n: number): string;
+/**
+ * The date `n` months after `iso`, on the same day of the month. When that day does not exist in the
+ * target month it is clamped to the last day: Jan 31 + 1 month is Feb 28 (or 29 in a leap year).
+ */
+declare function addMonths(iso: string, n: number): string;
+/** True when both ISO dates are the same day. */
+declare function isSameDay(a: string, b: string): boolean;
+/** -1, 0 or 1, for sorting ISO dates. */
+declare function compareISODate(a: string, b: string): -1 | 0 | 1;
+/** Today's local date as "YYYY-MM-DD". */
+declare function todayISODate(): string;
+
+/** The locale to format with: the one passed in, else the runtime default. */
+declare function resolveLocale(locale?: string): string;
+/**
+ * The first day of the week for a locale, 0 (Sunday) to 6 (Saturday). From `Intl.Locale` week data
+ * when the runtime has it (for example es-ES starts on Monday), otherwise Sunday.
+ */
+declare function defaultWeekStart(locale?: string): number;
+/**
+ * False on the server and during hydration, true after. Lets values that depend on the browser
+ * (its locale, today's date) render the same HTML on both sides, then update on the client.
+ */
+declare function useHydrated(): boolean;
+/** Locale used before hydration when none is passed, so server and client HTML match. */
+declare const FALLBACK_LOCALE = "en-US";
+/**
+ * The locale to render with. A passed locale is used as is. Without one, the server and the first
+ * client render use `FALLBACK_LOCALE`, then the browser's locale takes over. Pass `locale` in
+ * server-rendered apps to avoid that switch.
+ */
+declare function useResolvedLocale(locale?: string): string;
+
+export { Calendar, type CalendarProps, type CalendarRangeProps, type CalendarSingleProps, type DateRange, FALLBACK_LOCALE, addDays, addMonths, compareISODate, defaultWeekStart, isSameDay, parseISODate, resolveLocale, toISODate, todayISODate, useHydrated, useResolvedLocale };

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+import * as react from 'react';
+
+interface DateRange {
+    from: string | null;
+    to: string | null;
+}
+interface CalendarBaseProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "defaultValue" | "onChange"> {
+    /** The first day of the week, 0 (Sunday) to 6. Default: from the locale. */
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    /**
+     * BCP 47 tag, for example "es-ES". Default: the browser's locale. Server-rendered pages show "en-US" until
+     * hydration, then switch; pass `locale` to avoid the switch.
+     */
+    locale?: string;
+    /** Earliest selectable day, "YYYY-MM-DD". Days before it are disabled and navigation stops before its month. */
+    min?: string;
+    /** Latest selectable day, "YYYY-MM-DD". Days after it are disabled and navigation stops after its month. */
+    max?: string;
+    /** Disables more days. Disabled days can still receive focus, but cannot be selected. */
+    isDateDisabled?: (iso: string) => boolean;
+    /** The visible month, "YYYY-MM" (controlled). */
+    month?: string;
+    defaultMonth?: string;
+    onMonthChange?: (month: string) => void;
+    /** Shows one month, or two side by side (stacked on small screens). */
+    numberOfMonths?: 1 | 2;
+    /** Muted days from the adjacent months. Not selectable; clicking one moves to its month. Default true. */
+    showOutsideDays?: boolean;
+    /** Called when the user picks an enabled day, even when it is already the selected one. Used by DatePicker to close. */
+    onSelectDay?: (iso: string) => void;
+}
+interface CalendarSingleProps extends CalendarBaseProps {
+    mode?: "single";
+    value?: string | null;
+    defaultValue?: string | null;
+    onChange?: (iso: string | null) => void;
+    /** Clicking the selected day again clears it. Default false. */
+    allowDeselect?: boolean;
+}
+interface CalendarRangeProps extends CalendarBaseProps {
+    mode: "range";
+    value?: DateRange;
+    defaultValue?: DateRange;
+    onChange?: (range: DateRange) => void;
+}
+type CalendarProps = CalendarSingleProps | CalendarRangeProps;
+/**
+ * A month grid for picking one day, or a range of days. Values are "YYYY-MM-DD" strings.
+ * Follows the WAI-ARIA date picker grid: one tab stop, arrows move by day and week, PageUp and PageDown by month.
+ */
+declare const Calendar: react.ForwardRefExoticComponent<CalendarProps & react.RefAttributes<HTMLDivElement>>;
+
+/** The local calendar date of `date` as "YYYY-MM-DD". */
+declare function toISODate(date: Date): string;
+/** Local midnight of an ISO date. */
+declare function parseISODate(iso: string): Date;
+/** The date `n` days after `iso` (negative goes back). */
+declare function addDays(iso: string, n: number): string;
+/**
+ * The date `n` months after `iso`, on the same day of the month. When that day does not exist in the
+ * target month it is clamped to the last day: Jan 31 + 1 month is Feb 28 (or 29 in a leap year).
+ */
+declare function addMonths(iso: string, n: number): string;
+/** True when both ISO dates are the same day. */
+declare function isSameDay(a: string, b: string): boolean;
+/** -1, 0 or 1, for sorting ISO dates. */
+declare function compareISODate(a: string, b: string): -1 | 0 | 1;
+/** Today's local date as "YYYY-MM-DD". */
+declare function todayISODate(): string;
+
+/** The locale to format with: the one passed in, else the runtime default. */
+declare function resolveLocale(locale?: string): string;
+/**
+ * The first day of the week for a locale, 0 (Sunday) to 6 (Saturday). From `Intl.Locale` week data
+ * when the runtime has it (for example es-ES starts on Monday), otherwise Sunday.
+ */
+declare function defaultWeekStart(locale?: string): number;
+/**
+ * False on the server and during hydration, true after. Lets values that depend on the browser
+ * (its locale, today's date) render the same HTML on both sides, then update on the client.
+ */
+declare function useHydrated(): boolean;
+/** Locale used before hydration when none is passed, so server and client HTML match. */
+declare const FALLBACK_LOCALE = "en-US";
+/**
+ * The locale to render with. A passed locale is used as is. Without one, the server and the first
+ * client render use `FALLBACK_LOCALE`, then the browser's locale takes over. Pass `locale` in
+ * server-rendered apps to avoid that switch.
+ */
+declare function useResolvedLocale(locale?: string): string;
+
+export { Calendar, type CalendarProps, type CalendarRangeProps, type CalendarSingleProps, type DateRange, FALLBACK_LOCALE, addDays, addMonths, compareISODate, defaultWeekStart, isSameDay, parseISODate, resolveLocale, toISODate, todayISODate, useHydrated, useResolvedLocale };