gridsmith-ui 0.26.0 → 0.27.0

package/dist/utils.d.ts

@@ -10,4 +10,278 @@ declare const FOCUS_RING = "focus-visible:outline-none focus-visible:border-[var
 declare const FOCUS_WITHIN_RING = "focus-within:border-[var(--ds-border-focus)] focus-within:ring-2 focus-within:ring-[var(--ds-ring-active)]";
 declare const HAS_FOCUS_RING = "has-[:focus-visible]:border-[var(--ds-border-focus)] has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-[var(--ds-ring-active)]";
 
-export { ACTIVE_RING, FOCUS_RING, FOCUS_WITHIN_RING, GLASS_BACKDROP, GLASS_DROPDOWN, GLASS_OVERLAY, GLASS_SURFACE, HAS_FOCUS_RING, cn };
+/**
+ * The locale LocaleProvider writes in on the server for a page language and a request's Accept-Language header (Sprint
+ * 25.22's review), for server code's own dates and numbers: a server page passes it to the helpers from
+ * `gridsmith-ui/utils`, so its words read as the components' beside them. `requestLocale(LANG, (await
+ * headers()).get('accept-language'))`.
+ */
+declare function requestLocale(lang: string | undefined, acceptLanguage?: string | null): string;
+
+/** A day of the week as `Date.getDay()` counts them: Sunday 0, Monday 1 … Saturday 6. */
+type Weekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
+/**
+ * How something repeats (Sprint 25.19 R1): the iCalendar standard's rule (RFC 5545 `RRULE`), in the subset Outlook's and
+ * Google's menus write (P5), read in the event's local time. The quick choices are stored in the standard's implied form
+ * (P6): a weekly rule with no `weekdays`, a monthly rule with no `day` or `nth` and a bare yearly rule repeat on the
+ * start's own weekday, date or anniversary, so moving the event moves them. The event's own start is always its first
+ * occurrence.
+ */
+type RecurrenceFrequency = "daily" | "weekly" | "monthly" | "yearly";
+/** An nth weekday of a month: the first to the fourth, or the last (−1). A fifth weekday is the last. */
+type WeekOfMonth = 1 | 2 | 3 | 4 | -1;
+interface Recurrence {
+    freq: RecurrenceFrequency;
+    /** Every n days, weeks, months or years. Default 1. */
+    interval?: number;
+    /** Weekly: the days it repeats on, Sunday 0 to Saturday 6. Left out, the start's own weekday. */
+    weekdays?: Weekday[];
+    /** Monthly, or yearly with `month`: a day of the month, 1 to 31, or −1 for the last day. A month without the day is skipped. */
+    day?: number;
+    /** Monthly, or yearly with `month`: an nth weekday, `{ week: 1, weekday: 2 }` the first Tuesday. */
+    nth?: {
+        week: WeekOfMonth;
+        weekday: Weekday;
+    };
+    /** Yearly: the month, 1 to 12, with `day` or `nth`. A bare yearly rule repeats on the start's anniversary. */
+    month?: number;
+    /** The week's first day (WKST), which places a weekly rule's weeks. Default Monday, as RFC 5545 says. */
+    weekStart?: Weekday;
+    /**
+     * The last moment it occurs. A date at midnight includes its whole day ("until 30 November"); an all-day event's is a
+     * date. RecurrencePicker stores the end of the chosen day, which other apps read exactly. Left out with `count`, it
+     * never ends. A rule read back from JSON may carry it as a string: the library reads it as the date it was.
+     */
+    until?: Date;
+    /** How many times it occurs, the first included, and the excluded dates among them (RFC 5545). */
+    count?: number;
+}
+/** The fields a repeating event carries; a Calendar event has them as `repeat` and `exceptions` (P12: never `recurrence`). */
+interface RepeatingEvent {
+    id: string;
+    start: Date;
+    end?: Date;
+    allDay?: boolean;
+    /** The rule, or a rule string `parseRRule` reads ("RRULE:FREQ=WEEKLY;BYDAY=TU,TH"). */
+    repeat?: Recurrence | string;
+    /** The dates left out, as day keys in local time ("2026-10-20"): the original date of each occurrence removed or moved. */
+    exceptions?: string[];
+    /**
+     * On an occurrence, its series' id and its original date (a day key), as RFC 5545's RECURRENCE-ID links an edited
+     * instance to its series. Each occurrence `occurrences` gives carries it, and so does an occurrence changed on its own
+     * ("This event"), which the page stores under an id of its own: the series leaves the date out, and the edit helpers
+     * find it by its link.
+     */
+    series?: {
+        id: string;
+        date: string;
+    };
+}
+/** Which occurrences a change or a deletion applies to: this one, it and the ones after it, or the whole series. */
+type RecurrenceScope = "this" | "following" | "all";
+/**
+ * What a choice in RecurrenceScopeDialog does to the page's events: `events`, the list as it now is, for a page that
+ * keeps its events in state; or `save`, the events to write (new or changed, each by its id), and `remove`, the ids to
+ * delete, for a page that stores them elsewhere.
+ */
+interface RepeatChange<T> {
+    events: T[];
+    save: T[];
+    remove: string[];
+}
+/** One occurrence of a series: the event without its repeat fields, its own id, start and end, and where it came from. */
+type Occurrence<T extends RepeatingEvent> = Omit<T, "repeat" | "exceptions"> & {
+    id: string;
+    start: Date;
+    end?: Date;
+    /** The series' id and this occurrence's original date (a day key), which the edit helpers take. */
+    series: {
+        id: string;
+        date: string;
+    };
+};
+/**
+ * The rule a string holds, or null when it is outside P5's subset (the event is then drawn once, its rule kept as written):
+ * FREQ, INTERVAL and WKST; weekly BYDAY days; a monthly or yearly BYMONTHDAY, or one nth BYDAY ("1TU", or "TU" with
+ * BYSETPOS=1); a yearly BYMONTH with either; UNTIL (a date, a floating or a UTC date-time) or COUNT. The "RRULE:" prefix
+ * is optional. A daily rule with days (every weekday, as some apps write it) reads as weekly on them.
+ */
+declare function parseRRule(text: string): Recurrence | null;
+/**
+ * The rule as an RRULE string, "RRULE:FREQ=…", for an iCalendar file or another app. UNTIL is written as a date for an
+ * all-day event and in UTC for a timed one, as RFC 5545 asks.
+ */
+declare function toRRule(rule: Recurrence, { allDay }?: {
+    allDay?: boolean;
+}): string;
+/**
+ * A rule from a value: the object itself, the rule a string holds, or null for an unreadable string or none. A rule read
+ * back from JSON (storage, an API) has its end as a string, which is read as the date it was; an end that isn't a date
+ * makes the rule unreadable, so the event is drawn once rather than guessed at.
+ */
+declare function readRecurrence(value: Recurrence | string | undefined | null): Recurrence | null;
+/** The nth weekday a date is: the last when it is in its month's last seven days (a fifth Tuesday is the last). */
+declare function nthOf(date: Date): {
+    week: WeekOfMonth;
+    weekday: Weekday;
+};
+/**
+ * Every occurrence of a repeating event that overlaps [from, to), in order: the event without its repeat fields, each
+ * with the id "<id>::<date>", its own start and end (the same wall-clock times and number of days) and `series`, its
+ * original date. Its excluded dates are left out. An event that doesn't repeat, or whose rule can't be read, is itself,
+ * when it overlaps.
+ */
+declare function occurrences<T extends RepeatingEvent>(event: T, from: Date, to: Date): Array<T | Occurrence<T>>;
+/**
+ * The occurrence of a series on a day (a day key), or undefined when it has none that day (the rule skips it, or it is
+ * excluded): for a page whose Edit has an address of its own, which carries the series' id and the date. Given the
+ * page's events, an occurrence changed on its own on that date ("This event") is found too.
+ */
+declare function occurrenceOn<T extends RepeatingEvent>(series: T, date: string, events?: readonly T[]): Occurrence<T> | undefined;
+/**
+ * Saves the user's edit to an occurrence, for the scope they chose in RecurrenceScopeDialog: the page stores what it
+ * returns. `occurrence` is the event they opened, one the Calendar handed over or one changed on its own before (the
+ * page's own); `changes` the form's fields, every one or only those changed (only what differs from the opened event
+ * applies); `newId` an id of the page's, for the event or the series a choice makes.
+ * - "This event": the occurrence becomes an event of its own, linked to its series by `series`, its date left out of the
+ *   series; one changed on its own before just takes the edit.
+ * - "This and following events": the series ends the day before and a new one starts on the date, under `newId`, with
+ *   the edit; the events changed on their own from the date on go with it.
+ * - "All events": the series takes the edit, and a moved time or day moves it and its rule, so every earlier date stays.
+ * The events changed on their own keep what they changed themselves (a field, another day, other times) and follow the
+ * rest. A changed repeat removes them, as Outlook does, and their dates go back to the new rule (RecurrenceScopeDialog's
+ * `edited` says so first); a deleted date stays deleted.
+ */
+declare function saveOccurrence<T extends RepeatingEvent>(events: readonly T[], occurrence: Occurrence<T> | T, scope: RecurrenceScope, changes: Partial<T>, newId: string): RepeatChange<T>;
+/**
+ * Deletes an occurrence, for the scope the user chose in RecurrenceScopeDialog: the page stores what it returns. "This
+ * event" leaves its date out of the series (an event changed on its own is removed, and its date stays empty); "This
+ * and following events" ends the series the day before and removes the events changed on their own from the date on;
+ * "All events" removes the series and every event changed on its own.
+ */
+declare function deleteOccurrence<T extends RepeatingEvent>(events: readonly T[], occurrence: Occurrence<T> | T, scope: RecurrenceScope): RepeatChange<T>;
+/**
+ * How many of a series' events changed on their own each scope covers, for RecurrenceScopeDialog's `edited`: "This and
+ * following events" those from the occurrence's date on, "All events" every one.
+ */
+declare function countEdited<T extends RepeatingEvent>(events: readonly T[], occurrence: Occurrence<T> | T): {
+    following: number;
+    all: number;
+};
+/**
+ * The rule in words, for its date: "Every week on Tuesday and Thursday, until 30 November 2026", "Every month on the
+ * first Tuesday", "Every year on 6 October". The days and dates are written in the locale given (a component's
+ * useFormatLocale(), Sprint 25.20), else the browser's reading of the page's language.
+ */
+declare function describeRecurrence(rule: Recurrence, start: Date, locale?: string | undefined): string;
+interface RecurrencePreset {
+    /** The choice in words, as describeRecurrence writes it for the date. */
+    label: string;
+    rule: Recurrence;
+}
+/**
+ * The quick choices for a date, each one including it (P6): every day; every weekday, for a weekday; every week on its
+ * weekday; every month on its nth weekday (the fourth and "the last" both for a fourth one in a month's last seven days,
+ * only "the last" for a fifth); every month on its date, and on the last day when it is one; every year on its
+ * anniversary. The weekly, monthly-by-date and yearly choices are the
+ * implied form, so they follow the date when the event moves.
+ */
+declare function recurrencePresets(start: Date, locale?: string | undefined): RecurrencePreset[];
+/** Whether two rules repeat the same way (an `until` compared by its moment). */
+declare function sameRecurrence(a: Recurrence | null | undefined, b: Recurrence | null | undefined): boolean;
+
+/**
+ * Time zones by the browser's own names, and their offsets (Sprint 25.17 A28), apart from the TimezoneSelect component since
+ * Sprint 25.22 so a server can call them: nothing here needs React. `gridsmith-ui/utils` exports canonicalTimeZone and
+ * timeZoneOffset for server code; browserTimeZone reads the zone of whatever runs it, a server's own there.
+ */
+/**
+ * The browser's own name for a zone (Sprint 25.17 A28, R28-51): one browser always names a zone one way, so a stored
+ * "Asia/Calcutta" and a listed "Asia/Kolkata" are one zone, with no alias table shipped. An id the browser doesn't know
+ * stays as given.
+ */
+declare function canonicalTimeZone(zone: string): string;
+/**
+ * A zone's offset from UTC at an instant, as the locale given names it ("GMT+1", "GMT-5", "GMT+5:30"; a component's
+ * useFormatLocale(), else the browser's reading): read at that instant, so it follows daylight saving.
+ */
+declare function timeZoneOffset(zone: string, at?: Date, locale?: string | undefined): string;
+
+/**
+ * Calendar days, and ranges of them in words (Sprint 25.7, Part D). A calendar day is a whole-number day index: days since
+ * 1970-01-01, counted on UTC day boundaries, so every day is the same width and a clock change never stretches or shrinks
+ * one. A "YYYY-MM-DD" string is a calendar day in the user's zone and is never parsed as UTC (new Date("2026-03-03") is
+ * 2 March, 19:00 in New York). Apart from the time scale (lib/time-scale.ts) since Sprint 25.22, so a server can call
+ * them: nothing here needs React or a browser, and `gridsmith-ui/utils` exports them for server code. On a server a Date
+ * or a date-time string is read in the server's time zone; a calendar day or a day index is the same everywhere.
+ */
+/** A Date, or a string: "YYYY-MM-DD" is a calendar day; any other string is a date-time. */
+type DateInput = Date | string;
+type TimeZoom = "day" | "week" | "month" | "quarter";
+/** Narrow to wide. */
+declare const TIME_ZOOMS: readonly TimeZoom[];
+/**
+ * The day index of a date: "2026-03-03" → that calendar day's index; a Date or a date-time string → its local calendar
+ * day plus the fraction of the day its local clock shows (a day's first instant is the whole day); a number is a day
+ * index already, as the scale's own functions take it. NaN for anything else: null from JSON, a string that is no date.
+ */
+declare function dayOf(value: DateInput | number): number;
+/** Local midnight of that calendar day; a fraction adds that much of the day on the local clock. */
+declare function dateOfDay(day: number): Date;
+/**
+ * Where a range that ends at `value` stops. A whole-day end is inclusive: "2026-03-14" (or a Date at local midnight,
+ * as the date pickers give) → the start of 15 March. A date-time end is half-open: it stops at that moment, as a day
+ * index does. A range's start can make a midnight Date half-open too (scale.span, formatDateRange, timeExtent).
+ */
+declare function endDayOf(value: DateInput | number): number;
+/**
+ * The earliest start and the latest end of some ranges, as day indices for useTimeScale: the end is where the last
+ * range stops (inclusive for a whole day, as endDayOf), and a range with no end ends where it starts (a milestone).
+ * NaN for no dated range, which the scale shows as today. A range, a start or an end that is null is skipped.
+ */
+declare function timeExtent(ranges: Iterable<{
+    start: DateInput;
+    end?: DateInput;
+}>): {
+    start: number;
+    end: number;
+};
+interface DateRangeWords {
+    locale?: string;
+    /** Joins the two ends in place of Intl's separator. Default " to " in English, and Intl's own separator elsewhere. */
+    to?: string;
+    /** Intl options for the days. Default { day: "numeric", month: "long" }; the year is added when the ends' years differ. */
+    day?: Intl.DateTimeFormatOptions;
+    /** Intl options for the times of a date-time range. Default { hour: "2-digit", minute: "2-digit" }. */
+    time?: Intl.DateTimeFormatOptions;
+}
+/**
+ * A range in words, in the locale, for accessible names: "3 to 14 March", "28 September to 3 October", "16 September"
+ * for one day. The end is inclusive for a whole day, as scale.span (a day index is where the range stops). A date-time
+ * range is named by its times, and the end's day only when it differs: "Friday 23 October, 06:00 to 14:00". Intl
+ * joins each day and time in the locale's own way, and outside English the two ends too ("10/31(土曜日)～11/01(日曜日)");
+ * the year shows when the two ends are in different years. A null end is the start's own day; a start that is no date
+ * gives "".
+ */
+declare function formatDateRange(start: DateInput | number, end?: DateInput | number, words?: DateRangeWords): string;
+
+/**
+ * Sprint 25.9, A3 — what a chart's category axis holds, and how its labels fit. No Recharts here: the charts entry and
+ * the tests import it, and it never measures on its own (the measurer is handed in).
+ *
+ * - `categoryKind(labels)`: "scale" when every non-empty label is a date, a time, a period or a number, else "names".
+ *   Anchored patterns only — never `Date.parse`, which V8 lets read "Tier 1", "Sprint 1" and "Northern Region 2" as dates.
+ * - `createAxisMeasurer(el)`: canvas text widths in the axis's resolved font, read from a probe that carries
+ *   `font-size: var(--ds-font-size-xs)`, so a `calc()` token (`calc(16px * .75)`, a 14 px base) measures right.
+ * - `fitLabel(name, width, measure)`: one line; else two lines split at a space; else "…" on the second. Never drops it.
+ */
+type CategoryKind = "names" | "scale";
+/**
+ * Whether a category axis holds names or a scale (dates, times, periods, numbers). Every non-empty label must match an
+ * anchored pattern to be "scale"; an all-empty set is "scale". LineChart and AreaChart are always "scale"; BarChart and
+ * CompositeChart guess with this, and their `categoryKind` prop overrides the guess.
+ */
+declare function categoryKind(labels: ReadonlyArray<unknown>, locale?: string): CategoryKind;
+
+export { ACTIVE_RING, type CategoryKind, type DateInput, type DateRangeWords, FOCUS_RING, FOCUS_WITHIN_RING, GLASS_BACKDROP, GLASS_DROPDOWN, GLASS_OVERLAY, GLASS_SURFACE, HAS_FOCUS_RING, type Occurrence, type Recurrence, type RecurrenceFrequency, type RecurrencePreset, type RecurrenceScope, type RepeatChange, type RepeatingEvent, TIME_ZOOMS, type TimeZoom, type WeekOfMonth, type Weekday, canonicalTimeZone, categoryKind, cn, countEdited, dateOfDay, dayOf, deleteOccurrence, describeRecurrence, endDayOf, formatDateRange, nthOf, occurrenceOn, occurrences, parseRRule, readRecurrence, recurrencePresets, requestLocale, sameRecurrence, saveOccurrence, timeExtent, timeZoneOffset, toRRule };