@urbicon-ui/blocks 6.1.4

package/dist/components/DatePicker/datepicker.engine.js

@@ -0,0 +1,327 @@
+/**
+ * Date formatting and parsing utilities for DatePicker.
+ * Uses native Intl.DateTimeFormat — no external dependencies.
+ *
+ * @internal Engine functions are an internal API of the DatePicker
+ * component. They are exported for testing and re-use by sibling
+ * components in this package but are not part of the public surface;
+ * the supported entry points are the `DatePicker` and `DateRangePicker`
+ * Svelte components themselves.
+ */
+const defaultFormat = {
+    day: '2-digit',
+    month: '2-digit',
+    year: 'numeric'
+};
+function isValid(date) {
+    return !Number.isNaN(date.getTime());
+}
+function isSameDay(a, b) {
+    return (a.getFullYear() === b.getFullYear() &&
+        a.getMonth() === b.getMonth() &&
+        a.getDate() === b.getDate());
+}
+/**
+ * Format a Date as a locale-aware string. Guards Invalid Date and Intl
+ * errors with logging instead of silent fallback.
+ */
+export function formatDate(date, locale, options) {
+    if (!isValid(date)) {
+        console.warn('[DatePicker] formatDate received Invalid Date', { date, locale });
+        return '';
+    }
+    try {
+        return new Intl.DateTimeFormat(locale, options ?? defaultFormat).format(date);
+    }
+    catch (err) {
+        console.warn('[DatePicker] Intl.DateTimeFormat failed — falling back to ISO', {
+            locale,
+            options,
+            err
+        });
+        return date.toISOString().slice(0, 10);
+    }
+}
+/**
+ * Format a date range. Deliberately concatenates the two halves with a
+ * fixed " – " (U+2013, en-dash with spaces) separator instead of
+ * `Intl.DateTimeFormat#formatRange`. The native API would collapse
+ * shared components (year/month) and break round-trip parsing — the
+ * range "Mar 15 – 22, 2026" cannot be split back into two valid dates
+ * because the first half has no year. The fixed separator keeps
+ * `formatDateRange` and `parseDateRange` symmetric.
+ */
+export function formatDateRange(start, end, locale, options) {
+    if (!isValid(start) || !isValid(end)) {
+        console.warn('[DatePicker] formatDateRange received Invalid Date', { start, end, locale });
+        return '';
+    }
+    const fmt = options ?? defaultFormat;
+    const s = formatDate(start, locale, fmt);
+    const e = formatDate(end, locale, fmt);
+    if (!s || !e)
+        return '';
+    return `${s} – ${e}`;
+}
+function buildLocaleMatcher(locale, options) {
+    let parts;
+    try {
+        const probe = new Date(2024, 0, 5);
+        parts = new Intl.DateTimeFormat(locale, options).formatToParts(probe);
+    }
+    catch (err) {
+        console.warn('[DatePicker] buildLocaleMatcher failed to construct Intl formatter', {
+            locale,
+            options,
+            err
+        });
+        return null;
+    }
+    const fieldOrder = [];
+    let pattern = '^\\s*';
+    for (const part of parts) {
+        if (part.type === 'day') {
+            pattern += '([\\p{Nd}]{1,2})';
+            fieldOrder.push('day');
+        }
+        else if (part.type === 'month') {
+            pattern += '([\\p{Nd}]{1,2})';
+            fieldOrder.push('month');
+        }
+        else if (part.type === 'year') {
+            pattern += '([\\p{Nd}]{2,4})';
+            fieldOrder.push('year');
+        }
+        else if (part.type === 'literal') {
+            pattern += part.value
+                .replace(/[‎‏]/g, '') // strip RTL/LTR direction marks
+                .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+                .replace(/\s+/g, '\\s*');
+        }
+    }
+    pattern += '\\s*$';
+    if (fieldOrder.length !== 3) {
+        console.warn('[DatePicker] locale mask is not purely numeric — typed input will fall back to ISO', { locale, options, fieldOrder, parts });
+        return null;
+    }
+    try {
+        return { pattern: new RegExp(pattern, 'u'), fieldOrder };
+    }
+    catch (err) {
+        console.warn('[DatePicker] buildLocaleMatcher built an invalid RegExp', {
+            locale,
+            pattern,
+            err
+        });
+        return null;
+    }
+}
+/**
+ * Convert Unicode digits (Arabic-Indic, Persian, Devanagari, etc.) into
+ * an integer. `parseInt` only handles ASCII; for `\p{Nd}` matches we
+ * need to normalise via Unicode code-point arithmetic.
+ */
+function parseUnicodeDigits(s) {
+    let result = 0;
+    for (const ch of s) {
+        const cp = ch.codePointAt(0);
+        if (cp === undefined)
+            return NaN;
+        // Use Number constructor — covers all Unicode decimal digit blocks
+        // via the JS spec's StringToNumber on a single-codepoint string.
+        const digit = Number(ch);
+        if (Number.isNaN(digit))
+            return NaN;
+        result = result * 10 + digit;
+    }
+    return result;
+}
+function parseLocaleDate(input, locale, options) {
+    const matcher = buildLocaleMatcher(locale, options);
+    if (!matcher)
+        return null;
+    const match = matcher.pattern.exec(input);
+    if (!match)
+        return null;
+    let year;
+    let month;
+    let day;
+    matcher.fieldOrder.forEach((field, i) => {
+        const n = parseUnicodeDigits(match[i + 1]);
+        if (field === 'year')
+            year = n;
+        else if (field === 'month')
+            month = n;
+        else
+            day = n;
+    });
+    if (year === undefined || month === undefined || day === undefined)
+        return null;
+    if (Number.isNaN(year) || Number.isNaN(month) || Number.isNaN(day))
+        return null;
+    if (year < 100) {
+        // 2-digit year — pivot ±50 around the current year. Warn so DOB-flow
+        // bugs surface quickly: a user typing "01.01.74" in 2026 gets 2074,
+        // probably not what they meant.
+        const original = year;
+        const now = new Date().getFullYear();
+        const century = Math.floor(now / 100) * 100;
+        year = year + century;
+        if (year - now > 50)
+            year -= 100;
+        else if (now - year > 50)
+            year += 100;
+        console.warn('[DatePicker] 2-digit year expanded via pivot — pass a 4-digit year to avoid ambiguity', { input: original, resolved: year });
+    }
+    const monthIndex = month - 1;
+    const date = new Date(year, monthIndex, day);
+    if (date.getFullYear() !== year || date.getMonth() !== monthIndex || date.getDate() !== day) {
+        return null;
+    }
+    return date;
+}
+/**
+ * Parse a single date from user input. Tries the locale's formatted mask
+ * first (built via `Intl.DateTimeFormat#formatToParts`), then a strict
+ * YYYY-MM-DD ISO fallback parsed in LOCAL timezone. Returns `null` for
+ * anything that can't be unambiguously parsed.
+ *
+ * Supports any locale whose default mask is purely numeric (day, month,
+ * year). Locales with non-numeric month names (`month: 'long'`),
+ * weekday literals, or non-Gregorian calendars are NOT parseable — the
+ * caller should rely on calendar-picker UX or accept ISO input only.
+ */
+export function parseDate(input, locale, options) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return null;
+    const localeResult = parseLocaleDate(trimmed, locale, options ?? defaultFormat);
+    if (localeResult)
+        return localeResult;
+    const iso = trimmed.match(/^(\d{4})-(\d{1,2})-(\d{1,2})$/);
+    if (iso) {
+        const year = Number(iso[1]);
+        const month = Number(iso[2]) - 1;
+        const day = Number(iso[3]);
+        const date = new Date(year, month, day);
+        if (date.getFullYear() === year && date.getMonth() === month && date.getDate() === day) {
+            return date;
+        }
+    }
+    return null;
+}
+/**
+ * Range separator: only splits on UNAMBIGUOUS separators.
+ *
+ * - U+2013 EN DASH, U+2212 MINUS SIGN, U+2014 EM DASH: always treated
+ *   as range separators (none of these appear inside a date component).
+ * - Hyphen / slash / "bis" / "to": only when surrounded by whitespace,
+ *   so `15.03.2026 - 22.03.2026` splits but `15/03/2026` (a locale's
+ *   intra-date separator) stays whole.
+ * - Comma: requires whitespace on at least one side.
+ */
+const rangeSeparator = /\s+(?:-|\/|bis|to)\s+|\s*,\s+|\s*[–—−]\s*/i;
+/**
+ * Parse a date range string like "15.03.2026 – 22.03.2026". Splits on
+ * the locale-aware range separator and parses each half with `parseDate`.
+ * A single date with no separator is accepted as a single-day range
+ * (`{ start: d, end: d }`). Rejects inverted ranges (start after end).
+ */
+export function parseDateRange(input, locale, options) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return null;
+    const parts = trimmed.split(rangeSeparator);
+    if (parts.length === 1) {
+        const single = parseDate(parts[0], locale, options);
+        return single ? { start: single, end: single } : null;
+    }
+    if (parts.length !== 2)
+        return null;
+    const start = parseDate(parts[0], locale, options);
+    const end = parseDate(parts[1], locale, options);
+    if (!start || !end)
+        return null;
+    if (start.getTime() > end.getTime())
+        return null;
+    return { start, end };
+}
+function stripTime(d) {
+    return new Date(d.getFullYear(), d.getMonth(), d.getDate());
+}
+function endOfDay(d) {
+    return new Date(d.getFullYear(), d.getMonth(), d.getDate(), 23, 59, 59, 999);
+}
+/**
+ * Centralised predicate that respects min/max/disabledDates/isDateDisabled.
+ * Used by both calendar clicks and typed input so they validate identically.
+ *
+ * Defensive against bad inputs:
+ * - Invalid `minDate` / `maxDate` are ignored with a warning instead of
+ *   silently disabling the constraint.
+ * - Invalid entries in `disabledDates` are skipped with a warning.
+ * - Throws from `isDateDisabled` are caught and logged; the date is
+ *   then treated as allowed so a faulty predicate can't take the picker
+ *   down.
+ *
+ * Note: if `minDate > maxDate` after stripping time, every date is
+ * out-of-range. We warn once on that configuration to surface the bug.
+ */
+export function isDateAllowed(date, constraints) {
+    if (!isValid(date))
+        return false;
+    const { minDate, maxDate, disabledDates, isDateDisabled } = constraints;
+    let minBound;
+    if (minDate) {
+        if (!isValid(minDate)) {
+            console.warn('[DatePicker] minDate is Invalid Date — ignoring constraint', { minDate });
+        }
+        else {
+            minBound = stripTime(minDate).getTime();
+        }
+    }
+    let maxBound;
+    if (maxDate) {
+        if (!isValid(maxDate)) {
+            console.warn('[DatePicker] maxDate is Invalid Date — ignoring constraint', { maxDate });
+        }
+        else {
+            maxBound = endOfDay(maxDate).getTime();
+        }
+    }
+    if (minBound !== undefined && maxBound !== undefined && minBound > maxBound) {
+        console.warn('[DatePicker] minDate > maxDate — no date will satisfy both constraints', {
+            minDate,
+            maxDate
+        });
+    }
+    if (minBound !== undefined && date.getTime() < minBound)
+        return false;
+    if (maxBound !== undefined && date.getTime() > maxBound)
+        return false;
+    if (disabledDates) {
+        for (const d of disabledDates) {
+            if (!isValid(d)) {
+                console.warn('[DatePicker] disabledDates contains Invalid Date — skipping entry', {
+                    entry: d
+                });
+                continue;
+            }
+            if (isSameDay(d, date))
+                return false;
+        }
+    }
+    if (isDateDisabled) {
+        try {
+            if (isDateDisabled(date))
+                return false;
+        }
+        catch (err) {
+            console.warn('[DatePicker] isDateDisabled callback threw — treating date as allowed', {
+                date,
+                err
+            });
+        }
+    }
+    return true;
+}

package/dist/components/DatePicker/index.d.ts

@@ -0,0 +1,255 @@
+import type { HTMLAttributes } from 'svelte/elements';
+import type { MintProp } from '../../mint';
+import type { MonthIndex, WeekdayIndex } from '../../utils/date';
+import type { DateRange } from '../Calendar/calendar.types';
+import type { DateFormatOptions } from './datepicker.engine';
+/**
+ * @description Date input with calendar popup for selecting a single date. Supports min/max constraints, disabled dates, and format customization.
+ *
+ * The `value` prop accepts either a `Date` or an ISO timestamp string —
+ * useful when surrounding state is hydrated from JSON or a SQL driver
+ * that serialises timestamps as strings. `onValueChange` always reports
+ * back a `Date` (or `undefined`); use `toDateInputValue` from
+ * `@urbicon-ui/blocks` to project it back into a string state.
+ *
+ * @tag form
+ * @related DateRangePicker
+ * @related Calendar
+ * @related Input
+ *
+ * @example
+ * ```svelte
+ * <DatePicker
+ *   bind:value={selectedDate}
+ *   label="Date of birth"
+ *   placeholder="Select a date"
+ *   locale="en-US"
+ *   clearable
+ * />
+ * ```
+ *
+ * @example ISO string state (e.g. from JSON / Drizzle timestamp)
+ * ```svelte
+ * <script>
+ *   import { DatePicker, toDateInputValue } from '@urbicon-ui/blocks';
+ *   let isoDate = $state('2026-04-22T08:00:00Z');
+ * </script>
+ * <DatePicker
+ *   value={isoDate}
+ *   onValueChange={(d) => (isoDate = toDateInputValue(d))}
+ *   label="Period start"
+ * />
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <DatePicker
+ *   bind:value={deadline}
+ *   label="Deadline"
+ *   minDate={new Date()}
+ *   maxDate={new Date(2026, 11, 31)}
+ *   isDateDisabled={(d) => d.getDay() === 0 || d.getDay() === 6}
+ *   required
+ *   error={deadlineError}
+ * />
+ * ```
+ */
+export interface DatePickerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /**
+     * Currently selected date. Supports bind:value.
+     * Accepts a `Date`, an ISO timestamp string, or `null` / `undefined`.
+     * Internally coerced to a `Date`; the picker emits `Date` instances
+     * via {@link DatePickerProps.onValueChange}. When both `bind:value` and
+     * `onValueChange` are wired, both fire on every user-driven change —
+     * pick one to drive side-effects (saves, analytics) to avoid duplicates.
+     */
+    value?: Date | string | null;
+    /** Label above the input. */
+    label?: string;
+    /** Placeholder when no date is selected. */
+    placeholder?: string;
+    /** Intl.DateTimeFormat options for the displayed date. */
+    displayFormat?: DateFormatOptions;
+    /** Error message shown below the input. */
+    error?: string;
+    /** Helper text shown below the input. */
+    helper?: string;
+    /** Mark input as required. @default false */
+    required?: boolean;
+    /** Allow clearing the selected date. @default true */
+    clearable?: boolean;
+    /** Close popover after selecting a date. @default true */
+    closeOnSelect?: boolean;
+    /** Whether the popover closes on Escape key. @default true */
+    closeOnEscape?: boolean;
+    /** Whether the popover closes on outside click. @default true */
+    closeOnClickOutside?: boolean;
+    /**
+     * Fires after Escape closes the popover. Notification only — does NOT
+     * govern whether close happens. That is controlled by `closeOnEscape`.
+     */
+    onEscape?: () => void;
+    /**
+     * Fires after an outside click closes the popover. Notification only —
+     * does NOT govern whether close happens. That is controlled by
+     * `closeOnClickOutside`.
+     */
+    onClickOutside?: () => void;
+    /** BCP 47 locale for date formatting and calendar. @default 'de-DE' */
+    locale?: string;
+    /** First day of the week. 0 = Sunday, 1 = Monday. @default 1 */
+    weekStartsOn?: WeekdayIndex;
+    /** Show ISO week numbers. @default false */
+    showWeekNumbers?: boolean;
+    /** Show days from adjacent months. @default true */
+    showOutsideDays?: boolean;
+    /** Always show 6 weeks. @default false */
+    fixedWeeks?: boolean;
+    /** Earliest selectable date. */
+    minDate?: Date;
+    /** Latest selectable date. */
+    maxDate?: Date;
+    /** Specific dates that are disabled. */
+    disabledDates?: Date[];
+    /**
+     * Predicate that disables specific dates. Errors thrown by the
+     * predicate are caught and logged; the date is then treated as
+     * allowed so a faulty consumer callback can't take the picker down.
+     */
+    isDateDisabled?: (date: Date) => boolean;
+    /** Visual style of the calendar popup. @default 'default' */
+    calendarVariant?: 'default' | 'bordered' | 'ghost';
+    /** Input variant. @default 'outlined' */
+    inputVariant?: 'outlined' | 'filled' | 'ghost' | 'underline';
+    /** Component size. @default 'md' */
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    /** Fires when the selected date changes. */
+    onValueChange?: (value: Date | undefined) => void;
+    /** Fires when the popover opens or closes. */
+    onOpenChange?: (open: boolean) => void;
+    /** Disable the entire picker. @default false */
+    disabled?: boolean;
+    /** Micro-interaction preset. */
+    mint?: MintProp;
+    class?: string;
+    /** Default month shown when the picker opens without a value. `0`–`11`. */
+    defaultMonth?: MonthIndex;
+    /** Default year shown when the picker opens without a value. */
+    defaultYear?: number;
+    /**
+     * Shared `name` for native form submission. When set, a hidden input
+     * is rendered carrying the serialized date — matching what the user
+     * picked, so the visible input's locale-formatted display string is
+     * never submitted instead.
+     *
+     * Empty / unset values submit as `""` so the field still appears in
+     * the FormData payload.
+     */
+    name?: string;
+    /**
+     * Format used to serialise the date for the hidden form input.
+     * - `'date'` (default): `YYYY-MM-DD` in the local timezone — matches
+     *   the native `<input type="date">` payload and Zod schemas like
+     *   `z.string().regex(/^\d{4}-\d{2}-\d{2}$/).transform((v) => new Date(v))`.
+     * - `'iso'`: full ISO-8601 with `Z` suffix (UTC). Use this when the
+     *   downstream schema expects a parseable timestamp string (e.g. a
+     *   Drizzle `timestamp({ withTimezone: true, mode: 'date' })` column).
+     *
+     * Only relevant when {@link DatePickerProps.name} is set.
+     * @default 'date'
+     */
+    valueFormat?: 'date' | 'iso';
+}
+/**
+ * @description Date range input with dual-calendar popup for selecting start and end dates.
+ *
+ * @tag form
+ * @related DatePicker
+ * @related Calendar
+ */
+export interface DateRangePickerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /** Currently selected date range. Supports bind:value. */
+    value?: DateRange;
+    /** Label above the input. */
+    label?: string;
+    /** Placeholder when no range is selected. */
+    placeholder?: string;
+    /** Intl.DateTimeFormat options for displayed dates. */
+    displayFormat?: DateFormatOptions;
+    error?: string;
+    helper?: string;
+    required?: boolean;
+    clearable?: boolean;
+    /** Close popover after selecting both dates. @default true */
+    closeOnSelect?: boolean;
+    /** Whether the popover closes on Escape key. @default true */
+    closeOnEscape?: boolean;
+    /** Whether the popover closes on outside click. @default true */
+    closeOnClickOutside?: boolean;
+    /** Notification only — does NOT govern close behavior. */
+    onEscape?: () => void;
+    /** Notification only — does NOT govern close behavior. */
+    onClickOutside?: () => void;
+    locale?: string;
+    weekStartsOn?: WeekdayIndex;
+    showWeekNumbers?: boolean;
+    showOutsideDays?: boolean;
+    fixedWeeks?: boolean;
+    minDate?: Date;
+    maxDate?: Date;
+    disabledDates?: Date[];
+    /**
+     * Predicate that disables specific dates. Throws are caught and logged;
+     * the date is then treated as allowed.
+     */
+    isDateDisabled?: (date: Date) => boolean;
+    calendarVariant?: 'default' | 'bordered' | 'ghost';
+    inputVariant?: 'outlined' | 'filled' | 'ghost' | 'underline';
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    /**
+     * Fires when the selected range changes. During calendar selection
+     * the user clicks twice — once to set the start, once to set the
+     * end. `onValueChange` only fires when the range is *complete*
+     * (start ≠ end); the intermediate `{ start: d, end: d }` state
+     * does NOT fire this callback. Use `bind:value` if you need the
+     * in-progress state.
+     */
+    onValueChange?: (value: DateRange | undefined) => void;
+    onOpenChange?: (open: boolean) => void;
+    disabled?: boolean;
+    mint?: MintProp;
+    class?: string;
+    /** Default month shown when the picker opens without a value. `0`–`11`. */
+    defaultMonth?: MonthIndex;
+    /** Default year shown when the picker opens without a value. */
+    defaultYear?: number;
+    /**
+     * Shared base `name` for native form submission. When set, two hidden
+     * inputs are rendered — `{name}_start` and `{name}_end` — each
+     * carrying the serialized date, so the visible input's locale-formatted
+     * display string is never submitted instead.
+     *
+     * Empty range submits both halves as `""`. The `_start` / `_end`
+     * convention reflects the picker's domain language — date ranges read
+     * naturally as start/end rather than min/max.
+     */
+    name?: string;
+    /**
+     * Format used to serialise both range halves. See
+     * {@link DatePickerProps.valueFormat} for semantics.
+     * @default 'date'
+     */
+    valueFormat?: 'date' | 'iso';
+}
+export interface DatePickerPreset {
+    label: string;
+    value: Date;
+}
+export interface DateRangePreset {
+    label: string;
+    value: DateRange;
+}
+export type { DateRange } from '../Calendar/calendar.types';
+export { default as DatePicker } from './DatePicker.svelte';
+export { default as DateRangePicker } from './DateRangePicker.svelte';
+export type { DateFormatOptions } from './datepicker.engine';

package/dist/components/DatePicker/index.js

@@ -0,0 +1,2 @@
+export { default as DatePicker } from './DatePicker.svelte';
+export { default as DateRangePicker } from './DateRangePicker.svelte';