gbs-add-block 1.2.9 → 1.2.11

package/source/beta-components/datepicker/core/calendar.ts

@@ -0,0 +1,263 @@
+import type {
+  CalendarDay,
+  CalendarMonth,
+  CalendarWeek,
+  DateInput,
+  DateLimits,
+  DateRange,
+} from "./types";
+
+/**
+ * Every date in this package is a local-time Date at midnight. Keeping one
+ * convention means day comparisons never depend on hours, time zones or DST,
+ * and `toISODate` never shifts a day the way `toISOString` does.
+ */
+export function startOfDay(date: Date): Date {
+  const copy = new Date(date.getTime());
+  copy.setHours(0, 0, 0, 0);
+  return copy;
+}
+
+/** Strict `yyyy-mm-dd` in local time; null for anything else, including `2026-02-31`. */
+export function parseISODate(text: string): Date | null {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(text.trim());
+  if (!match) return null;
+  const year = Number(match[1]);
+  const month = Number(match[2]) - 1;
+  const day = Number(match[3]);
+  const date = new Date(year, month, day);
+  date.setHours(0, 0, 0, 0);
+  const valid =
+    date.getFullYear() === year && date.getMonth() === month && date.getDate() === day;
+  return valid ? date : null;
+}
+
+export function toISODate(date: Date): string {
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${date.getFullYear()}-${month}-${day}`;
+}
+
+/** Normalizes a prop value. ISO strings are read as local dates, not UTC. */
+export function toDate(value: DateInput | null | undefined): Date | null {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "string") {
+    const iso = parseISODate(value);
+    if (iso) return iso;
+  }
+  const date = value instanceof Date ? new Date(value.getTime()) : new Date(value);
+  return Number.isNaN(date.getTime()) ? null : startOfDay(date);
+}
+
+/** Negative when `a` is the earlier day, 0 on the same day. Ignores the time. */
+export function compareDay(a: Date, b: Date): number {
+  return (
+    a.getFullYear() - b.getFullYear() || a.getMonth() - b.getMonth() || a.getDate() - b.getDate()
+  );
+}
+
+export const isSameDay = (a: Date | null | undefined, b: Date | null | undefined): boolean =>
+  a != null && b != null && compareDay(a, b) === 0;
+
+export const isSameMonth = (a: Date, b: Date): boolean =>
+  a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth();
+
+export const daysInMonth = (year: number, month: number): number =>
+  new Date(year, month + 1, 0).getDate();
+
+export function addDays(date: Date, amount: number): Date {
+  const copy = new Date(date.getFullYear(), date.getMonth(), date.getDate() + amount);
+  copy.setHours(0, 0, 0, 0);
+  return copy;
+}
+
+/** Keeps the day of the month where the target month is long enough (Jan 31 + 1 → Feb 28). */
+export function addMonths(date: Date, amount: number): Date {
+  const year = date.getFullYear();
+  const month = date.getMonth() + amount;
+  const day = Math.min(date.getDate(), daysInMonth(year, month));
+  const copy = new Date(year, month, day);
+  copy.setHours(0, 0, 0, 0);
+  return copy;
+}
+
+export const startOfMonth = (date: Date): Date =>
+  new Date(date.getFullYear(), date.getMonth(), 1);
+
+export const endOfMonth = (date: Date): Date =>
+  new Date(date.getFullYear(), date.getMonth() + 1, 0);
+
+export function clampDate(date: Date, min?: Date | null, max?: Date | null): Date {
+  if (min && compareDay(date, min) < 0) return startOfDay(min);
+  if (max && compareDay(date, max) > 0) return startOfDay(max);
+  return date;
+}
+
+export function isDayDisabled(date: Date, limits: DateLimits = {}): boolean {
+  if (limits.min && compareDay(date, limits.min) < 0) return true;
+  if (limits.max && compareDay(date, limits.max) > 0) return true;
+  return limits.isDateDisabled?.(date) === true;
+}
+
+interface WeekInfoLocale {
+  getWeekInfo?(): { firstDay: number };
+  weekInfo?: { firstDay: number };
+}
+
+/**
+ * First day of the week for a locale, 0 = Sunday. Browsers expose this through
+ * `Intl.Locale`; where they don't, ISO Monday is used unless `explicit` is given.
+ */
+export function resolveWeekStart(locale?: string, explicit?: number): number {
+  if (explicit !== undefined) return ((explicit % 7) + 7) % 7;
+  try {
+    const tag = locale ?? new Intl.DateTimeFormat().resolvedOptions().locale;
+    const info = new Intl.Locale(tag) as unknown as WeekInfoLocale;
+    const firstDay = info.getWeekInfo?.().firstDay ?? info.weekInfo?.firstDay;
+    if (typeof firstDay === "number") return firstDay % 7;
+  } catch {
+    // Locale data is unavailable in this runtime; fall through to the ISO default.
+  }
+  return 1;
+}
+
+/** ISO 8601 week number: week 1 is the one holding the first Thursday of the year. */
+export function getISOWeek(date: Date): number {
+  const target = startOfDay(date);
+  target.setDate(target.getDate() - ((target.getDay() + 6) % 7) + 3);
+  const firstThursday = new Date(target.getFullYear(), 0, 4);
+  firstThursday.setDate(firstThursday.getDate() - ((firstThursday.getDay() + 6) % 7) + 3);
+  const week = 7 * 24 * 60 * 60 * 1000;
+  return 1 + Math.round((target.getTime() - firstThursday.getTime()) / week);
+}
+
+export interface BuildMonthOptions extends DateLimits {
+  /** 0 = Sunday. Default Monday. */
+  weekStartsOn?: number;
+  /** Always six week rows, so the popover height never jumps. Default true. */
+  fixedWeeks?: boolean;
+  /** Injected so a test (or a server render) can pin "today". */
+  today?: Date;
+}
+
+export function buildMonth(
+  year: number,
+  month: number,
+  options: BuildMonthOptions = {},
+): CalendarMonth {
+  const { weekStartsOn = 1, fixedWeeks = true, today = startOfDay(new Date()) } = options;
+  const first = new Date(year, month, 1);
+  const lead = (first.getDay() - weekStartsOn + 7) % 7;
+  const rows = fixedWeeks ? 6 : Math.ceil((lead + daysInMonth(year, month)) / 7);
+
+  const weeks: CalendarWeek[] = [];
+  let cursor = addDays(first, -lead);
+  for (let row = 0; row < rows; row++) {
+    const days: CalendarDay[] = [];
+    for (let column = 0; column < 7; column++) {
+      const weekday = cursor.getDay();
+      days.push({
+        date: cursor,
+        day: cursor.getDate(),
+        key: toISODate(cursor),
+        outside: cursor.getMonth() !== month || cursor.getFullYear() !== year,
+        today: compareDay(cursor, today) === 0,
+        weekend: weekday === 0 || weekday === 6,
+        disabled: isDayDisabled(cursor, options),
+      });
+      cursor = addDays(cursor, 1);
+    }
+    weeks.push({ weekNumber: getISOWeek(days[0].date), days });
+  }
+  return { year, month, weeks };
+}
+
+/** `count` consecutive months starting at the month of `start`. */
+export function buildMonths(
+  start: Date,
+  count: number,
+  options: BuildMonthOptions = {},
+): CalendarMonth[] {
+  return Array.from({ length: Math.max(1, count) }, (_, index) => {
+    const month = addMonths(startOfMonth(start), index);
+    return buildMonth(month.getFullYear(), month.getMonth(), options);
+  });
+}
+
+/** Puts a backwards range the right way round, so dragging in either direction works. */
+export function normalizeRange(range: DateRange): DateRange {
+  const { start, end } = range;
+  if (start && end && compareDay(start, end) > 0) return { start: end, end: start };
+  return range;
+}
+
+export function isInRange(date: Date, start: Date | null, end: Date | null): boolean {
+  if (!start || !end) return false;
+  return compareDay(date, start) >= 0 && compareDay(date, end) <= 0;
+}
+
+export interface MoveOptions {
+  weekStartsOn?: number;
+  /** Swaps the arrow keys, so "next day" stays to the reading-forward side. */
+  rtl?: boolean;
+  shiftKey?: boolean;
+}
+
+/** Where a key press moves the focused day, or null when the key isn't ours. */
+export function moveByKey(date: Date, key: string, options: MoveOptions = {}): Date | null {
+  const { weekStartsOn = 1, rtl = false, shiftKey = false } = options;
+  const offsetInWeek = (date.getDay() - weekStartsOn + 7) % 7;
+  switch (key) {
+    case rtl ? "ArrowRight" : "ArrowLeft":
+      return addDays(date, -1);
+    case rtl ? "ArrowLeft" : "ArrowRight":
+      return addDays(date, 1);
+    case "ArrowUp":
+      return addDays(date, -7);
+    case "ArrowDown":
+      return addDays(date, 7);
+    case "Home":
+      return addDays(date, -offsetInWeek);
+    case "End":
+      return addDays(date, 6 - offsetInWeek);
+    case "PageUp":
+      return addMonths(date, shiftKey ? -12 : -1);
+    case "PageDown":
+      return addMonths(date, shiftKey ? 12 : 1);
+    default:
+      return null;
+  }
+}
+
+/** Arrow-key movement inside the month and year panels. Returns null for other keys. */
+export function moveInGrid(
+  index: number,
+  key: string,
+  columns: number,
+  count: number,
+  rtl = false,
+): number | null {
+  const clamp = (next: number) => Math.max(0, Math.min(count - 1, next));
+  switch (key) {
+    case rtl ? "ArrowRight" : "ArrowLeft":
+      return clamp(index - 1);
+    case rtl ? "ArrowLeft" : "ArrowRight":
+      return clamp(index + 1);
+    case "ArrowUp":
+      return clamp(index - columns);
+    case "ArrowDown":
+      return clamp(index + columns);
+    case "Home":
+      return 0;
+    case "End":
+      return count - 1;
+    default:
+      return null;
+  }
+}
+
+/** The page of years holding `year`, so the year panel pages in steady blocks. */
+export function yearPage(year: number, size = 12): number[] {
+  const start = Math.floor(year / size) * size;
+  return Array.from({ length: size }, (_, index) => start + index);
+}

package/source/beta-components/datepicker/core/format.ts

@@ -0,0 +1,170 @@
+import { parseISODate } from "./calendar";
+
+/** `Intl.DateTimeFormat` is expensive to build, and these are reused every render. */
+const formatters = new Map<string, Intl.DateTimeFormat>();
+
+function formatter(locale: string | undefined, options: Intl.DateTimeFormatOptions) {
+  const key = `${locale ?? ""}|${JSON.stringify(options)}`;
+  let found = formatters.get(key);
+  if (!found) {
+    found = new Intl.DateTimeFormat(locale, options);
+    formatters.set(key, found);
+  }
+  return found;
+}
+
+export const DEFAULT_DATE_FORMAT: Intl.DateTimeFormatOptions = {
+  year: "numeric",
+  month: "short",
+  day: "numeric",
+};
+export const DEFAULT_INPUT_PLACEHOLDER = "dd/mm/yyyy";
+
+export function formatDate(
+  date: Date,
+  locale?: string,
+  options: Intl.DateTimeFormatOptions = DEFAULT_DATE_FORMAT,
+): string {
+  return formatter(locale, options).format(date);
+}
+
+export function formatMonthYear(year: number, month: number, locale?: string): string {
+  return formatter(locale, { year: "numeric", month: "long" }).format(new Date(year, month, 1));
+}
+
+export function monthNames(locale?: string, width: "long" | "short" = "long"): string[] {
+  const format = formatter(locale, { month: width });
+  return Array.from({ length: 12 }, (_, month) => format.format(new Date(2024, month, 1)));
+}
+
+export interface WeekdayName {
+  short: string;
+  long: string;
+}
+
+/** The seven weekday names, ordered from `weekStartsOn`. */
+export function weekdayNames(locale?: string, weekStartsOn = 1): WeekdayName[] {
+  const short = formatter(locale, { weekday: "short" });
+  const long = formatter(locale, { weekday: "long" });
+  // 2024-01-07 was a Sunday, so index 0 lines up with `Date.prototype.getDay`.
+  return Array.from({ length: 7 }, (_, offset) => {
+    const date = new Date(2024, 0, 7 + ((weekStartsOn + offset) % 7));
+    return { short: short.format(date), long: long.format(date) };
+  });
+}
+
+export type DateField = "day" | "month" | "year";
+
+/** The order a locale writes a numeric date in, used for parsing and the placeholder. */
+export function fieldOrder(locale?: string): DateField[] {
+  const parts = formatter(locale, {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).formatToParts(new Date(2024, 10, 22));
+  const order = parts
+    .map((part) => part.type)
+    .filter((type): type is DateField => type === "day" || type === "month" || type === "year");
+  return order.length === 3 ? order : ["day", "month", "year"];
+}
+
+function separator(locale?: string): string {
+  const parts = formatter(locale, {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).formatToParts(new Date(2024, 10, 22));
+  const literal = parts.find((part) => part.type === "literal" && part.value.trim());
+  return literal ? literal.value.trim() : "/";
+}
+
+/** A hint in the locale's own order, e.g. `dd/mm/yyyy` or `mm/dd/yyyy`. */
+export function inputPlaceholder(locale?: string): string {
+  if (!locale) return DEFAULT_INPUT_PLACEHOLDER;
+  const hint: Record<DateField, string> = { day: "dd", month: "mm", year: "yyyy" };
+  return fieldOrder(locale)
+    .map((field) => hint[field])
+    .join(separator(locale));
+}
+
+/** Two-digit years follow the usual pivot: 00-68 is 2000s, 69-99 is 1900s. */
+function expandYear(year: number): number {
+  if (year >= 100) return year;
+  return year <= 68 ? 2000 + year : 1900 + year;
+}
+
+function build(year: number, month: number, day: number): Date | null {
+  if (month < 0 || month > 11 || day < 1 || day > 31) return null;
+  const date = new Date(year, month, day);
+  date.setHours(0, 0, 0, 0);
+  const valid =
+    date.getFullYear() === year && date.getMonth() === month && date.getDate() === day;
+  return valid ? date : null;
+}
+
+/** Matches a written month name, long or short, by either being a prefix of the other. */
+function monthFromWords(words: string, locale?: string): number | null {
+  const needle = words.toLocaleLowerCase();
+  const names = [...monthNames(locale, "long"), ...monthNames(locale, "short")];
+  const index = names.findIndex((name) => {
+    const candidate = name.toLocaleLowerCase().replace(/\.$/, "");
+    return candidate.startsWith(needle) || needle.startsWith(candidate);
+  });
+  return index === -1 ? null : index % 12;
+}
+
+/**
+ * Reads what someone typed into the field. ISO is accepted everywhere; anything
+ * else is read in the locale's field order, so `03/04/2026` is 3 April in
+ * en-GB and 4 March in en-US. Month names work too (`12 Mar 2026`).
+ * Missing parts fall back to `reference`. Returns null when it isn't a date.
+ */
+export function parseDate(
+  text: string,
+  locale?: string,
+  reference: Date = new Date(),
+): Date | null {
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+
+  const iso = parseISODate(trimmed);
+  if (iso) return iso;
+
+  let month: number | null = null;
+  const words = trimmed.match(/\p{L}+/gu);
+  if (words) {
+    month = monthFromWords(words.join(" "), locale);
+    if (month === null) return null;
+  }
+
+  const numbers = (trimmed.match(/\d+/g) ?? []).map(Number);
+  if (numbers.length === 0) return null;
+
+  const order = fieldOrder(locale);
+
+  if (month !== null) {
+    // A month name was given, so the numbers are the day and maybe the year.
+    if (numbers.length === 1) {
+      return build(reference.getFullYear(), month, numbers[0]);
+    }
+    const yearFirst = numbers[0] >= 32;
+    const year = expandYear(yearFirst ? numbers[0] : numbers[1]);
+    const day = yearFirst ? numbers[1] : numbers[0];
+    return build(year, month, day);
+  }
+
+  if (numbers.length >= 3) {
+    const fields = numbers[0] >= 1000 ? (["year", "month", "day"] as DateField[]) : order;
+    const value = (field: DateField) => numbers[fields.indexOf(field)];
+    return build(expandYear(value("year")), value("month") - 1, value("day"));
+  }
+
+  if (numbers.length === 2) {
+    const dayFirst = order.indexOf("day") < order.indexOf("month");
+    const day = dayFirst ? numbers[0] : numbers[1];
+    const monthNumber = dayFirst ? numbers[1] : numbers[0];
+    return build(reference.getFullYear(), monthNumber - 1, day);
+  }
+
+  return build(reference.getFullYear(), reference.getMonth(), numbers[0]);
+}

package/source/beta-components/datepicker/core/index.ts

@@ -0,0 +1,40 @@
+// Framework-free date helpers: the same calendar building, parsing and
+// formatting the components use, so a server (or a test) can reproduce them.
+export {
+  addDays,
+  addMonths,
+  buildMonth,
+  buildMonths,
+  clampDate,
+  compareDay,
+  daysInMonth,
+  endOfMonth,
+  getISOWeek,
+  isDayDisabled,
+  isInRange,
+  isSameDay,
+  isSameMonth,
+  moveByKey,
+  moveInGrid,
+  normalizeRange,
+  parseISODate,
+  resolveWeekStart,
+  startOfDay,
+  startOfMonth,
+  toDate,
+  toISODate,
+  yearPage,
+} from "./calendar";
+export type { BuildMonthOptions, MoveOptions } from "./calendar";
+export {
+  DEFAULT_DATE_FORMAT,
+  fieldOrder,
+  formatDate,
+  formatMonthYear,
+  inputPlaceholder,
+  monthNames,
+  parseDate,
+  weekdayNames,
+} from "./format";
+export type { DateField, WeekdayName } from "./format";
+export type * from "./types";

package/source/beta-components/datepicker/core/types.ts

@@ -0,0 +1,68 @@
+/** Values accepted wherever a date comes in: a Date, an ISO `yyyy-mm-dd` string or a timestamp. */
+export type DateInput = Date | string | number;
+
+export interface DateRange {
+  start: Date | null;
+  end: Date | null;
+}
+
+export type DatePickerSize = "sm" | "md" | "lg";
+
+/** Panel shown inside the popover. */
+export type CalendarView = "days" | "months" | "years";
+
+export interface CalendarDay {
+  date: Date;
+  /** Day of the month, 1-31. */
+  day: number;
+  /** `yyyy-mm-dd` in local time: a stable key, and safe to compare. */
+  key: string;
+  /** Belongs to a neighbouring month. */
+  outside: boolean;
+  today: boolean;
+  weekend: boolean;
+  disabled: boolean;
+}
+
+export interface CalendarWeek {
+  /** ISO week number, shown when `showWeekNumbers` is set. */
+  weekNumber: number;
+  days: CalendarDay[];
+}
+
+export interface CalendarMonth {
+  year: number;
+  /** 0-11, as in `Date.prototype.getMonth`. */
+  month: number;
+  weeks: CalendarWeek[];
+}
+
+/** What makes a day unselectable. */
+export interface DateLimits {
+  min?: Date | null;
+  max?: Date | null;
+  isDateDisabled?(date: Date): boolean;
+}
+
+export interface DatePickerLocaleText {
+  calendarLabel: string;
+  openCalendar: string;
+  clear: string;
+  today: string;
+  previousMonth: string;
+  nextMonth: string;
+  previousYears: string;
+  nextYears: string;
+  /** Button that switches the day grid to the month and year panels. */
+  chooseMonthYear: string;
+  monthPanelLabel: string;
+  yearPanelLabel: string;
+  weekNumber: string;
+  startDate: string;
+  endDate: string;
+  invalidDate: string;
+  outOfRange: string;
+  presets: string;
+  selectedDate(date: string): string;
+  selectedRange(start: string, end: string): string;
+}

package/source/beta-components/datepicker/index.ts

@@ -0,0 +1,16 @@
+export { DatePicker } from "./react/DatePicker";
+export type { DatePickerProps } from "./react/DatePicker";
+export { DateRangePicker } from "./react/DateRangePicker";
+export type { DateRangePickerProps, DateRangeInput } from "./react/DateRangePicker";
+export type { DatePreset } from "./react/CalendarPanel";
+export { formatWith, useDatePicker } from "./react/useDatePicker";
+export type { DatePickerEngine, RangeField, UseDatePickerParams } from "./react/useDatePicker";
+export { defaultDatePickerText } from "./react/locale";
+export type { DayState } from "./react/Calendar";
+export type {
+  DateFormat,
+  DatePickerHandle,
+  DatePickerSharedProps,
+  DatePickerSlot,
+} from "./react/props";
+export * from "./core";