@astryxdesign/core 0.7.8 → 0.7.9-canary.07992bb

package/dist/utils/calendarSystem.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @file calendarSystem.ts
+ * @input A calendar identifier and Gregorian PlainDates
+ * @output Calendar months located by their Gregorian days, their year and
+ *   month numbers, month and year steps, dates from calendar fields,
+ *   availability of each calendar, and calendar labels and digits
+ * @position Shared date utility; read by the i18n calendar resolution, by
+ *   Calendar, and by its public hooks. Values stay Gregorian PlainDates. Temporal owns the arithmetic of
+ *   every calendar whose months are not Gregorian.
+ */
+import type { Locale } from '../i18n/types.js';
+import type { PlainDate } from './dateTypes.js';
+/**
+ * A calendar system that date components can show: the calendars that
+ * ECMA-402 and Temporal require. Values stay Gregorian ISO dates in every
+ * calendar.
+ */
+export type CalendarSystem = 'gregory' | 'iso8601' | 'buddhist' | 'roc' | 'japanese' | 'persian' | 'indian' | 'hebrew' | 'chinese' | 'dangi' | 'coptic' | 'ethiopic' | 'ethioaa' | 'islamic-civil' | 'islamic-tbla' | 'islamic-umalqura';
+export declare const CALENDAR_SYSTEMS: ReadonlyArray<CalendarSystem>;
+/** Whether the calendar's months and days are the Gregorian ones. */
+export declare function isGregorianAligned(calendar: CalendarSystem): boolean;
+export declare function isCalendarSystem(value: string): value is CalendarSystem;
+/**
+ * Whether this runtime can show the calendar. Gregorian-aligned calendars
+ * always can. The others need a `Temporal` that knows the calendar: a
+ * polyfill build without non-ISO calendars throws for them.
+ */
+export declare function isCalendarSystemAvailable(calendar: CalendarSystem): boolean;
+/** A month of a calendar, located by its first and last Gregorian days. */
+export interface CalendarMonth {
+    readonly start: PlainDate;
+    readonly end: PlainDate;
+    readonly length: number;
+}
+/** The day of the calendar month that a Gregorian date falls on. */
+export declare function calendarDayOfMonth(calendar: CalendarSystem, pd: PlainDate): number;
+/** The calendar month that contains a Gregorian date. */
+export declare function calendarMonthOf(calendar: CalendarSystem, pd: PlainDate): CalendarMonth;
+/**
+ * A calendar month by its year and its position in that year, as
+ * `Temporal.PlainDate` numbers them: month 13 exists in a Hebrew leap year.
+ */
+export interface CalendarYearMonth {
+    readonly year: number;
+    readonly month: number;
+}
+/** The year and month numbers of a calendar month. */
+export declare function calendarYearMonthOf(calendar: CalendarSystem, month: CalendarMonth): CalendarYearMonth;
+/**
+ * The calendar month with these year and month numbers. A month past the end
+ * of its year becomes the last month of that year, as Temporal constrains it.
+ */
+export declare function calendarMonthFromYearMonth(calendar: CalendarSystem, { year, month }: CalendarYearMonth): CalendarMonth;
+/** The calendar month `n` months after `month`, or before it when negative. */
+export declare function calendarAddMonths(calendar: CalendarSystem, month: CalendarMonth, n: number): CalendarMonth;
+/**
+ * Moves a date by `n` calendar months. It keeps the day of the month and
+ * clamps it to the length of the target month.
+ */
+export declare function calendarShiftMonths(calendar: CalendarSystem, pd: PlainDate, n: number): PlainDate;
+/**
+ * Moves a date by `n` calendar years, to the same month of the target year.
+ * It clamps the day of the month. A leap month that the target year does not
+ * have becomes its common counterpart, because Temporal keeps the month code
+ * and constrains it.
+ */
+export declare function calendarShiftYears(calendar: CalendarSystem, pd: PlainDate, n: number): PlainDate;
+/** Whether a Gregorian date falls inside a calendar month. */
+export declare function isInCalendarMonth(pd: PlainDate, month: CalendarMonth): boolean;
+/**
+ * The stand-alone month and year label of a calendar month, such as
+ * "Aban 1405 AP". It formats a day in the middle of the month: in the
+ * Japanese calendar an era can start inside a month, and most days of that
+ * month then belong to the era of its middle day.
+ */
+export declare function formatCalendarMonthLabel(calendar: CalendarSystem, month: CalendarMonth, locale: Locale): string;
+/**
+ * Formats a Gregorian date in the calendar, such as "Friday, Aban 8, 1405 AP".
+ * The label always names the month and day that the grid shows. Intl and the
+ * runtime's Temporal can disagree on where a month of the Chinese or Dangi
+ * calendar starts; the label then takes its month and year from the middle of
+ * the Temporal month, and its day from Temporal.
+ */
+export declare function formatCalendarDate(calendar: CalendarSystem, pd: PlainDate, options: Intl.DateTimeFormatOptions, locale: Locale): string;
+/** The parts of `formatCalendarDate`'s label. */
+export declare function formatCalendarDateToParts(calendar: CalendarSystem, pd: PlainDate, options: Intl.DateTimeFormatOptions, locale: Locale): Intl.DateTimeFormatPart[];
+/**
+ * Formats an instant as `formatCalendarDate` formats the day it falls on in
+ * `timeZone`, the host's zone when omitted. Intl writes any time of day that
+ * `options` asks for.
+ */
+export declare function formatCalendarInstant(calendar: CalendarSystem, instant: Date, options: Intl.DateTimeFormatOptions, locale: Locale, timeZone?: string): string;
+/**
+ * The fields of a date written in a calendar. A field gives either `year` or
+ * `era` with `eraYear`, and either `monthCode` (such as `M05L` for a leap
+ * month) or `month`, the month's position in its year.
+ */
+export interface CalendarDateFields {
+    readonly year?: number;
+    readonly era?: string;
+    readonly eraYear?: number;
+    readonly monthCode?: string;
+    readonly month?: number;
+    readonly day: number;
+}
+/**
+ * The Gregorian date for fields written in a calendar that needs Temporal,
+ * or null when the calendar does not have that date. Temporal validates the
+ * fields and never adjusts them: 30 Esfand in a common Persian year is null.
+ */
+export declare function calendarDateFromFields(calendar: CalendarSystem, fields: CalendarDateFields): PlainDate | null;
+/** The number of months in the calendar year that contains a date. */
+export declare function calendarMonthsInYear(calendar: CalendarSystem, pd: PlainDate): number;
+//# sourceMappingURL=calendarSystem.d.ts.map

package/dist/utils/calendarSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calendarSystem.d.ts","sourceRoot":"","sources":["../../src/utils/calendarSystem.ts"],"names":[],"mappings":"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"}

package/dist/utils/calendarSystem.js

@@ -0,0 +1,386 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file calendarSystem.ts
+ * @input A calendar identifier and Gregorian PlainDates
+ * @output Calendar months located by their Gregorian days, their year and
+ *   month numbers, month and year steps, dates from calendar fields,
+ *   availability of each calendar, and calendar labels and digits
+ * @position Shared date utility; read by the i18n calendar resolution, by
+ *   Calendar, and by its public hooks. Values stay Gregorian PlainDates. Temporal owns the arithmetic of
+ *   every calendar whose months are not Gregorian.
+ */
+
+import { dateTimeFormatAtCall, dateTimeFormatFor, plainDateAddDays, plainDateAddMonths, plainDateFormatDayNumber, plainDateFormatStandaloneMonthYear, plainDateFormatToParts, plainDateFromDate, plainDateFromInstant, plainDateIsInRange, getDaysInMonth } from "./plainDate.js";
+
+/**
+ * A calendar system that date components can show: the calendars that
+ * ECMA-402 and Temporal require. Values stay Gregorian ISO dates in every
+ * calendar.
+ */
+
+// A record, so the compiler checks that it lists every calendar exactly once.
+const KNOWN_CALENDARS = {
+  gregory: true,
+  iso8601: true,
+  buddhist: true,
+  roc: true,
+  japanese: true,
+  persian: true,
+  indian: true,
+  hebrew: true,
+  chinese: true,
+  dangi: true,
+  coptic: true,
+  ethiopic: true,
+  ethioaa: true,
+  'islamic-civil': true,
+  'islamic-tbla': true,
+  'islamic-umalqura': true
+};
+export const CALENDAR_SYSTEMS = Object.keys(KNOWN_CALENDARS);
+const GREGORIAN_ALIGNED = new Set(['gregory', 'iso8601', 'buddhist', 'roc', 'japanese']);
+
+/** Whether the calendar's months and days are the Gregorian ones. */
+export function isGregorianAligned(calendar) {
+  return GREGORIAN_ALIGNED.has(calendar);
+}
+export function isCalendarSystem(value) {
+  return Object.hasOwn(KNOWN_CALENDARS, value);
+}
+
+// The published types must not need the `esnext.temporal` library.
+// This module declares only the Temporal members it reads.
+
+function getTemporal() {
+  const temporal = globalThis.Temporal;
+  return typeof temporal?.PlainDate === 'function' ? temporal : undefined;
+}
+
+// The key is the Temporal object, so a polyfill that loads later gets its
+// own probe.
+const supportedCalendars = new WeakMap();
+
+/**
+ * Whether this runtime can show the calendar. Gregorian-aligned calendars
+ * always can. The others need a `Temporal` that knows the calendar: a
+ * polyfill build without non-ISO calendars throws for them.
+ */
+export function isCalendarSystemAvailable(calendar) {
+  if (isGregorianAligned(calendar)) {
+    return true;
+  }
+  const temporal = getTemporal();
+  if (temporal == null) {
+    return false;
+  }
+  let known = supportedCalendars.get(temporal);
+  if (known == null) {
+    known = new Map();
+    supportedCalendars.set(temporal, known);
+  }
+  let isSupported = known.get(calendar);
+  if (isSupported == null) {
+    try {
+      new temporal.PlainDate(2000, 1, 1, calendar);
+      isSupported = true;
+    } catch {
+      isSupported = false;
+    }
+    known.set(calendar, isSupported);
+  }
+  return isSupported;
+}
+function inCalendar(calendar, pd) {
+  const temporal = getTemporal();
+  if (temporal == null) {
+    throw new Error(`The "${calendar}" calendar needs Temporal.`);
+  }
+  return new temporal.PlainDate(pd.year, pd.month, pd.day, calendar);
+}
+function toGregorian(date) {
+  const iso = date.withCalendar('iso8601');
+  return {
+    year: iso.year,
+    month: iso.month,
+    day: iso.day
+  };
+}
+
+/** A month of a calendar, located by its first and last Gregorian days. */
+
+function makeMonth(start, length) {
+  return {
+    start,
+    end: plainDateAddDays(start, length - 1),
+    length
+  };
+}
+function gregorianMonth(year, month) {
+  return makeMonth({
+    year,
+    month,
+    day: 1
+  }, getDaysInMonth(year, month));
+}
+function temporalMonth(firstDay) {
+  return makeMonth(toGregorian(firstDay), firstDay.daysInMonth);
+}
+
+/** The day of the calendar month that a Gregorian date falls on. */
+export function calendarDayOfMonth(calendar, pd) {
+  return isGregorianAligned(calendar) ? pd.day : inCalendar(calendar, pd).day;
+}
+
+/** The calendar month that contains a Gregorian date. */
+export function calendarMonthOf(calendar, pd) {
+  if (isGregorianAligned(calendar)) {
+    return gregorianMonth(pd.year, pd.month);
+  }
+  return temporalMonth(inCalendar(calendar, pd).with({
+    day: 1
+  }));
+}
+
+/**
+ * A calendar month by its year and its position in that year, as
+ * `Temporal.PlainDate` numbers them: month 13 exists in a Hebrew leap year.
+ */
+
+// Temporal counts the years of these Gregorian-aligned calendars from another
+// epoch: 2026 is 2569 in `buddhist` and 115 in `roc`.
+const GREGORIAN_YEAR_OFFSETS = {
+  buddhist: 543,
+  roc: -1911
+};
+
+/** The year and month numbers of a calendar month. */
+export function calendarYearMonthOf(calendar, month) {
+  if (isGregorianAligned(calendar)) {
+    return {
+      year: month.start.year + (GREGORIAN_YEAR_OFFSETS[calendar] ?? 0),
+      month: month.start.month
+    };
+  }
+  const {
+    year,
+    month: monthOfYear
+  } = inCalendar(calendar, month.start);
+  return {
+    year,
+    month: monthOfYear
+  };
+}
+
+/**
+ * The calendar month with these year and month numbers. A month past the end
+ * of its year becomes the last month of that year, as Temporal constrains it.
+ */
+export function calendarMonthFromYearMonth(calendar, {
+  year,
+  month
+}) {
+  if (isGregorianAligned(calendar)) {
+    return gregorianMonth(year - (GREGORIAN_YEAR_OFFSETS[calendar] ?? 0), month);
+  }
+  // `with` replaces the year and month of any date in the calendar.
+  return temporalMonth(inCalendar(calendar, {
+    year: 2000,
+    month: 1,
+    day: 1
+  }).with({
+    year,
+    month,
+    day: 1
+  }));
+}
+
+/** The calendar month `n` months after `month`, or before it when negative. */
+export function calendarAddMonths(calendar, month, n) {
+  if (n === 0) {
+    return month;
+  }
+  if (isGregorianAligned(calendar)) {
+    const {
+      year,
+      month: monthOfYear
+    } = plainDateAddMonths(month.start, n);
+    return gregorianMonth(year, monthOfYear);
+  }
+  return temporalMonth(inCalendar(calendar, month.start).add({
+    months: n
+  }));
+}
+
+/**
+ * Moves a date by `n` calendar months. It keeps the day of the month and
+ * clamps it to the length of the target month.
+ */
+export function calendarShiftMonths(calendar, pd, n) {
+  if (isGregorianAligned(calendar)) {
+    return plainDateAddMonths(pd, n);
+  }
+  return toGregorian(inCalendar(calendar, pd).add({
+    months: n
+  }));
+}
+
+/**
+ * Moves a date by `n` calendar years, to the same month of the target year.
+ * It clamps the day of the month. A leap month that the target year does not
+ * have becomes its common counterpart, because Temporal keeps the month code
+ * and constrains it.
+ */
+export function calendarShiftYears(calendar, pd, n) {
+  if (isGregorianAligned(calendar)) {
+    return plainDateAddMonths(pd, n * 12);
+  }
+  return toGregorian(inCalendar(calendar, pd).add({
+    years: n
+  }));
+}
+
+/** Whether a Gregorian date falls inside a calendar month. */
+export function isInCalendarMonth(pd, month) {
+  return plainDateIsInRange(pd, [month.start, month.end]);
+}
+
+/**
+ * The stand-alone month and year label of a calendar month, such as
+ * "Aban 1405 AP". It formats a day in the middle of the month: in the
+ * Japanese calendar an era can start inside a month, and most days of that
+ * month then belong to the era of its middle day.
+ */
+export function formatCalendarMonthLabel(calendar, month, locale) {
+  return plainDateFormatStandaloneMonthYear(plainDateAddDays(month.start, Math.floor(month.length / 2)), locale, labelCalendar(calendar));
+}
+
+// Intl has no month names for `iso8601`. Labels use `gregory`, which has the
+// same months and days.
+function labelCalendar(calendar) {
+  return calendar === 'iso8601' ? 'gregory' : calendar;
+}
+function formatToParts(calendar, pd, options, locale) {
+  return plainDateFormatToParts(pd, {
+    ...options,
+    calendar
+  }, locale);
+}
+const MONTH_PART_TYPES = new Set(['era', 'year', 'relatedYear', 'yearName', 'month']);
+function monthPartsKey(parts) {
+  return parts.filter(part => MONTH_PART_TYPES.has(part.type)).map(part => part.value).join('|');
+}
+
+/**
+ * Formats a Gregorian date in the calendar, such as "Friday, Aban 8, 1405 AP".
+ * The label always names the month and day that the grid shows. Intl and the
+ * runtime's Temporal can disagree on where a month of the Chinese or Dangi
+ * calendar starts; the label then takes its month and year from the middle of
+ * the Temporal month, and its day from Temporal.
+ */
+export function formatCalendarDate(calendar, pd, options, locale) {
+  return joinParts(formatCalendarDateToParts(calendar, pd, options, locale));
+}
+
+/** The parts of `formatCalendarDate`'s label. */
+export function formatCalendarDateToParts(calendar, pd, options, locale) {
+  const parts = formatToParts(labelCalendar(calendar), pd, options, locale);
+  return withTemporalDay(calendar, pd, parts, options, locale);
+}
+
+// Returns `parts` itself where Intl already names Temporal's month and day.
+function withTemporalDay(calendar, pd, parts, options, locale) {
+  if (isGregorianAligned(calendar) || !isCalendarSystemAvailable(calendar)) {
+    return parts;
+  }
+  const date = inCalendar(calendar, pd);
+  const middle = plainDateAddDays(pd, Math.floor(date.daysInMonth / 2) - (date.day - 1));
+  const middleParts = formatToParts(calendar, middle, options, locale);
+  const intlDay = formatToParts(calendar, pd, {
+    day: 'numeric'
+  }, 'en-u-nu-latn').find(part => part.type === 'day')?.value;
+  if (Number(intlDay) === date.day && monthPartsKey(parts) === monthPartsKey(middleParts)) {
+    return parts;
+  }
+  const {
+    numberingSystem
+  } = dateTimeFormatFor(locale, {
+    ...options,
+    calendar,
+    timeZone: 'UTC'
+  }).resolvedOptions();
+  const middleValues = new Map(middleParts.map(part => [part.type, part.value]));
+  return parts.map(part => part.type === 'day' ? {
+    ...part,
+    value: plainDateFormatDayNumber(date.day, locale, numberingSystem)
+  } : MONTH_PART_TYPES.has(part.type) ? {
+    ...part,
+    value: middleValues.get(part.type) ?? part.value
+  } : part);
+}
+
+/**
+ * Formats an instant as `formatCalendarDate` formats the day it falls on in
+ * `timeZone`, the host's zone when omitted. Intl writes any time of day that
+ * `options` asks for.
+ */
+export function formatCalendarInstant(calendar, instant, options, locale, timeZone) {
+  return instantLabel(calendar, instant, options, locale, timeZone).text;
+}
+function instantLabel(calendar, instant, options, locale, timeZone) {
+  const format = dateTimeFormatAtCall(locale, {
+    ...options,
+    ...(timeZone === undefined ? {} : {
+      timeZone
+    }),
+    calendar: labelCalendar(calendar)
+  });
+  const parts = format.formatToParts(instant);
+  const day = timeZone === undefined ? plainDateFromDate(instant) : plainDateFromInstant(instant.getTime(), timeZone);
+  const fixed = withTemporalDay(calendar, day, parts, options, locale);
+  const isIntl = fixed === parts;
+  return {
+    format,
+    isIntl,
+    text: isIntl ? format.format(instant) : joinParts(fixed)
+  };
+}
+function joinParts(parts) {
+  return parts.map(part => part.value).join('');
+}
+
+/**
+ * The fields of a date written in a calendar. A field gives either `year` or
+ * `era` with `eraYear`, and either `monthCode` (such as `M05L` for a leap
+ * month) or `month`, the month's position in its year.
+ */
+
+/**
+ * The Gregorian date for fields written in a calendar that needs Temporal,
+ * or null when the calendar does not have that date. Temporal validates the
+ * fields and never adjusts them: 30 Esfand in a common Persian year is null.
+ */
+export function calendarDateFromFields(calendar, fields) {
+  const temporal = getTemporal();
+  if (temporal == null) {
+    throw new Error(`The "${calendar}" calendar needs Temporal.`);
+  }
+  try {
+    return toGregorian(temporal.PlainDate.from({
+      ...fields,
+      calendar
+    }, {
+      overflow: 'reject'
+    }));
+  } catch (error) {
+    if (error instanceof RangeError || error instanceof TypeError) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/** The number of months in the calendar year that contains a date. */
+export function calendarMonthsInYear(calendar, pd) {
+  return isGregorianAligned(calendar) ? 12 : inCalendar(calendar, pd).monthsInYear;
+}

package/dist/utils/flatTree.d.ts

@@ -1,11 +1,12 @@
 /**
  * @file flatTree.ts
  * @input A DOM node
- * @output Exports parentAcrossShadow, and containsAlongFlatTree, which walks it
+ * @output Exports parentAcrossShadow, containsAlongFlatTree, which walks it,
+ *   and deepActiveElement
  * @position The flat-tree parent the browser scrolls and dispatches
- *   through, shared by the gesture host's native-scroll probe and the
+ *   through, shared by the gesture host's native-scroll probe, the
  *   selection lock (which the press feedback controller uses without the
- *   gesture system)
+ *   gesture system) and the Layer module's input hold
  */
 /** The node's parent, crossing out of shadow roots. */
 export declare function parentAcrossShadow(node: Node): Node | null;
@@ -14,4 +15,6 @@ export declare function parentAcrossShadow(node: Node): Node | null;
  * shadow root to its host, which `Node.contains` does not follow.
  */
 export declare function containsAlongFlatTree(ancestor: Node, node: Node): boolean;
+/** The focused element of `doc`, inside open shadow roots too. */
+export declare function deepActiveElement(doc: Document | null | undefined): Element | null;
 //# sourceMappingURL=flatTree.d.ts.map

package/dist/utils/flatTree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flatTree.d.ts","sourceRoot":"","sources":["../../src/utils/flatTree.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,uDAAuD;AACvD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAa1D;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAOzE"}
+{"version":3,"file":"flatTree.d.ts","sourceRoot":"","sources":["../../src/utils/flatTree.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,uDAAuD;AACvD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAa1D;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAOzE;AAED,kEAAkE;AAClE,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,GAC/B,OAAO,GAAG,IAAI,CAMhB"}

package/dist/utils/flatTree.js

@@ -3,11 +3,12 @@
 /**
  * @file flatTree.ts
  * @input A DOM node
- * @output Exports parentAcrossShadow, and containsAlongFlatTree, which walks it
+ * @output Exports parentAcrossShadow, containsAlongFlatTree, which walks it,
+ *   and deepActiveElement
  * @position The flat-tree parent the browser scrolls and dispatches
- *   through, shared by the gesture host's native-scroll probe and the
+ *   through, shared by the gesture host's native-scroll probe, the
  *   selection lock (which the press feedback controller uses without the
- *   gesture system)
+ *   gesture system) and the Layer module's input hold
  */
 
 /** The node's parent, crossing out of shadow roots. */
@@ -35,4 +36,13 @@ export function containsAlongFlatTree(ancestor, node) {
     }
   }
   return false;
+}
+
+/** The focused element of `doc`, inside open shadow roots too. */
+export function deepActiveElement(doc) {
+  let active = doc?.activeElement ?? null;
+  while (active?.shadowRoot?.activeElement != null) {
+    active = active.shadowRoot.activeElement;
+  }
+  return active;
 }

package/dist/utils/hitArea.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hitArea.d.ts","sourceRoot":"","sources":["../../src/utils/hitArea.ts"],"names":[],"mappings":"AA6BA,+BAA+B;AAC/B,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,mEAAmE;AACnE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,qDAAqD;AACrD,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,6CAA6C;AAC7C,eAAO,MAAM,aAAa,EAAE,SAAkD,CAAC;AAE/E;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;CAKvB,CAAC;AAmCX;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,OAAO,EACf,UAAU,EAAE,aAAa,CAAC,OAAO,CAAC,EAClC,OAAO,GAAE,MAAyB,GACjC,SAAS,CA4CX;AAYD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,EAC7B,OAAO,GAAE,MAAyB,GACjC,MAAM,CAoBR;AAED,gDAAgD;AAChD,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAI5E;AAmdD,iCAAiC;AACjC,MAAM,WAAW,mBAAmB;IAClC,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAW3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,EACrC,EAAC,OAA0B,EAAC,GAAE,mBAAwB,GACrD,MAAM,IAAI,CAyDZ"}
+{"version":3,"file":"hitArea.d.ts","sourceRoot":"","sources":["../../src/utils/hitArea.ts"],"names":[],"mappings":"AAgCA,+BAA+B;AAC/B,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,mEAAmE;AACnE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,qDAAqD;AACrD,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,6CAA6C;AAC7C,eAAO,MAAM,aAAa,EAAE,SAAkD,CAAC;AAE/E;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;CAKvB,CAAC;AAmCX;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,OAAO,EACf,UAAU,EAAE,aAAa,CAAC,OAAO,CAAC,EAClC,OAAO,GAAE,MAAyB,GACjC,SAAS,CA4CX;AAYD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,EAC7B,OAAO,GAAE,MAAyB,GACjC,MAAM,CAoBR;AAED,gDAAgD;AAChD,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAI5E;AAsjBD,iCAAiC;AACjC,MAAM,WAAW,mBAAmB;IAClC,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAW3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,EACrC,EAAC,OAA0B,EAAC,GAAE,mBAAwB,GACrD,MAAM,IAAI,CAyDZ"}