@nexterajs/ui 0.0.1

package/types/nexterajs-ui-intl.d.ts

@@ -0,0 +1,125 @@
+import { DateTime } from 'luxon';
+import { InjectionToken } from '@angular/core';
+
+interface NxeParsedNumberFormat {
+    prefix: string;
+    suffix: string;
+    useGrouping: boolean;
+    /**
+     * Digits per group, read from the pattern: `#,##0` is 3, `#,#0` is 2. Optional because
+     * callers construct this shape by hand as well as through {@link parseNumberFormat};
+     * omitted means dx's usual 3.
+     */
+    groupSize?: number;
+    minInt: number;
+    minFrac: number;
+    maxFrac: number;
+}
+/** Parse an LDML pattern into a {@link NxeParsedNumberFormat}, or `null` for raw (no format). */
+declare function parseNumberFormat(pattern: string | undefined | null): NxeParsedNumberFormat | null;
+/** Round half-away-from-zero to `frac` fraction digits (DevExtreme rounding), fp-safe. */
+declare function roundHalfAwayFromZero(value: number, frac: number): number;
+/** Format a number with the parsed pattern. `null`/`NaN` → `''`. */
+/**
+ * The characters that separate groups and the fraction.
+ *
+ * The LDML pattern always writes `,` for grouping and `.` for the decimal point — that is the
+ * pattern language, not the output. Which characters actually get rendered is a locale decision,
+ * and it is the one that split this file: one consuming app needs `1,234.50`, another needs
+ * `1.250.000,50`, and hardcoding either forces the other to fork.
+ */
+interface NxeNumberSeparators {
+    readonly group: string;
+    readonly decimal: string;
+}
+/** DevExtreme's default, and this library's. */
+declare const NXE_EN_US_SEPARATORS: NxeNumberSeparators;
+/** Indonesian house style, used by several of the consuming applications. */
+declare const NXE_ID_SEPARATORS: NxeNumberSeparators;
+declare function formatNumber(value: number | null | undefined, fmt: NxeParsedNumberFormat | null, separators?: NxeNumberSeparators): string;
+/** Parse a (possibly formatted) string into a number; strips grouping/literals. Empty → `null`. */
+declare function parseNumber(text: string | null | undefined, separators?: NxeNumberSeparators): number | null;
+
+/** The app-wide serialization format (matches DevExtreme `dateSerializationFormat`). */
+declare const NXE_DATE_SERIALIZATION_FORMAT = "yyyy-MM-dd'T'HH:mm:ss";
+/** DevExtreme global default `displayFormat` (`dxDateBox.defaultOptions`). */
+declare const NXE_DEFAULT_DISPLAY_FORMAT = "dd-MMM-yyyy";
+/** Default `displayFormat` for `type="datetime"`. */
+declare const NXE_DEFAULT_DATETIME_DISPLAY_FORMAT = "dd-MMM-yyyy HH:mm";
+/** Default `displayFormat` for `type="time"`. */
+declare const NXE_DEFAULT_TIME_DISPLAY_FORMAT = "HH:mm";
+/** Parse a bound value (wall-clock ISO string, full ISO, Date, or DateTime) into a Luxon DateTime. */
+declare function parseDateValue(value: unknown): DateTime | null;
+/** Serialize a DateTime back to the `"yyyy-MM-ddTHH:mm:ss"` string the rest of the app expects. */
+declare function serializeDate(dt: DateTime): string;
+/**
+ * Whether a value carries a real time of day.
+ *
+ * This is the one place that states what `00:00:00` MEANS in the app's serialization format: not
+ * "midnight", but "no time was chosen". Every date-only editor in the app writes exactly midnight,
+ * so the calendar's all-day-vs-timed split, the grid's display format and anything else that has to
+ * tell the two apart all read it from here and cannot drift.
+ */
+declare function hasTimeOfDay(value: unknown): boolean;
+/**
+ * Whether a start/end pair describes a whole-day range.
+ *
+ * Deliberately "every end that is PRESENT is midnight", not "start is midnight AND end is midnight".
+ * Half-filled pairs are a supported shape — the calendar endpoint folds `start ?? end` and treats a
+ * row carrying only one of the two as a single-day event — and a rule that demanded both would call
+ * such a row timed on the strength of the end that is not there.
+ *
+ * A pair with neither end is all-day by this reading. Degenerate, and unreachable in practice: a row
+ * with no dates at all cannot overlap a window, so the endpoint never returns one.
+ */
+declare function isAllDayRange(start: unknown, end: unknown): boolean;
+/** Format a DateTime for display per `displayFormat` (DevExtreme tokens map 1:1 to Luxon). */
+declare function formatDisplay(dt: DateTime | null, displayFormat: string): string;
+/**
+ * Parse user-typed text, trying in order: the display format; a lenient variant of it; for a format
+ * carrying time tokens, its date-only head (keeping `base`'s time); then ISO.
+ *
+ * `base` is what stops a datetime field from being destructive. Without it, typing just the date
+ * into a `dd-MMM-yyyy HH:mm` box either resets the time to midnight or — because the strict pass
+ * rejects the text outright — nulls the whole field. Callers editing an existing value should pass
+ * it; the parameter is optional so the date-only call sites need no change.
+ */
+declare function parseDisplay(text: string, displayFormat: string, base?: DateTime | null): DateTime | null;
+/** Calendar zoom level (DevExtreme `dxCalendar.zoomLevel`). */
+type NxeCalendarZoom = 'month' | 'year' | 'decade' | 'century';
+interface NxePeriodCell {
+    /** First day of the period (month / year / decade). */
+    anchor: DateTime;
+    label: string;
+    /** Belongs to the adjacent decade/century (rendered dimmed, DevExtreme `other-view`). */
+    other: boolean;
+}
+/**
+ * Build the 4×3 period grid for a zoomed-out calendar view (mirrors DevExtreme):
+ * `year` → Jan..Dec, `decade` → decadeStart−1..decadeStart+10, `century` → 12 decades
+ * from centuryStart−10, labelled `"2020 - 2029"`.
+ */
+declare function buildPeriodCells(zoom: Exclude<NxeCalendarZoom, 'month'>, view: DateTime): NxePeriodCell[];
+/** Build the 6×7 day grid (Sunday-first) for the calendar popup of `viewMonth`. */
+declare function buildCalendarWeeks(viewMonth: DateTime): DateTime[][];
+
+/**
+ * The grouping and decimal characters every number editor renders with.
+ *
+ * DevExtreme solves this with a global `DevExpress.localization.locale()`; the Angular equivalent
+ * is a provider, so an application states it once at bootstrap:
+ *
+ * ```ts
+ * providers: [{ provide: NXE_NUMBER_SEPARATORS, useValue: NXE_ID_SEPARATORS }]
+ * ```
+ *
+ * This exists because the alternative already happened: with the separators hardcoded, an
+ * application that needed `1.250.000,50` instead of `1,234.50` forked the format engine to get
+ * them, and that single file is why its copy of the library could not be merged back.
+ *
+ * Defaults to en-US, which is DevExtreme's default and what the pattern language itself writes.
+ */
+declare const NXE_NUMBER_SEPARATORS: InjectionToken<NxeNumberSeparators>;
+
+export { NXE_DATE_SERIALIZATION_FORMAT, NXE_DEFAULT_DATETIME_DISPLAY_FORMAT, NXE_DEFAULT_DISPLAY_FORMAT, NXE_DEFAULT_TIME_DISPLAY_FORMAT, NXE_EN_US_SEPARATORS, NXE_ID_SEPARATORS, NXE_NUMBER_SEPARATORS, buildCalendarWeeks, buildPeriodCells, formatDisplay, formatNumber, hasTimeOfDay, isAllDayRange, parseDateValue, parseDisplay, parseNumber, parseNumberFormat, roundHalfAwayFromZero, serializeDate };
+export type { NxeCalendarZoom, NxeNumberSeparators, NxeParsedNumberFormat, NxePeriodCell };