@crewlethq/ui 0.2.0 → 0.3.0

package/dist/TimeWindowPicker/TimeWindowPicker.d.ts

@@ -0,0 +1,231 @@
+export type TimeWindowMode = 'relative' | 'absolute';
+export type TimeWindowTimezone = 'local' | 'utc';
+/**
+ * A relative window whose start is a CALENDAR BOUNDARY rather than a duration
+ * back from now.
+ *
+ * Two, and both are convention-free. "This week" and "this month" are the ones
+ * that look like obvious neighbours and are not: a week begins on a different
+ * day in different places, so the span alone would not say when it starts, and
+ * the answer would have to be threaded through every pure function here from
+ * the picker's own `firstDayOfWeek`. A caller that wants a month passes `30d`
+ * or an absolute range.
+ */
+export type TimeWindowSpan = 'today' | 'yesterday';
+export declare const TIME_WINDOW_SPANS: readonly TimeWindowSpan[];
+export interface TimeWindowValue {
+    kind: TimeWindowMode;
+    /**
+     * A rolling duration for the relative mode: `15m`, `1h`, `24h`, `7d`. It
+     * resolves against the moment it is read, so a window set yesterday still
+     * means the last seven days today.
+     */
+    duration?: string | undefined;
+    /**
+     * A calendar-aligned span for the relative mode, INSTEAD of a duration:
+     * "today" starts at midnight rather than 24 hours ago. A value carrying
+     * both is one value holding two windows; the span is the more specific of
+     * the two, so it is the one that is kept.
+     */
+    span?: TimeWindowSpan | undefined;
+    /** A datetime-local string for the absolute mode (YYYY-MM-DDTHH:MM:SS). */
+    from?: string | undefined;
+    to?: string | undefined;
+    /**
+     * How the absolute strings and the calendar spans are read: `local` is the
+     * reader's wall clock, `utc` treats midnight as UTC midnight. It travels
+     * with the value, so a saved window round-trips.
+     */
+    timezone?: TimeWindowTimezone | undefined;
+}
+/**
+ * One window on the panel's rail, named the way a reader would say it.
+ *
+ * A preset is IDENTIFIED BY WHAT IT MEANS rather than by an id of its own:
+ * two presets for `7d` would be one window with two names, and the trigger
+ * would have to pick one of them to draw.
+ */
+export interface TimeWindowPreset {
+    /** What a reader calls it: "Last 7 days". */
+    label: string;
+    /** A rolling duration: `15m`, `1h`, `24h`, `7d`, `30d`. */
+    duration?: string | undefined;
+    /** A calendar-aligned span, instead of a duration. */
+    span?: TimeWindowSpan | undefined;
+}
+export interface TimeWindowBounds {
+    /** The earliest day a reader may choose, as a YYYY-MM-DD or datetime-local string. */
+    min?: string | undefined;
+    /**
+     * The latest. It defaults to TODAY, because every window this drives reads
+     * something that has already happened: a range ending next Tuesday returns
+     * nothing and looks like a range that found nothing.
+     */
+    max?: string | undefined;
+}
+/** Every string the picker renders on its own, and every phrase it builds. */
+export interface TimeWindowLabels {
+    /** What the trigger shows before a window is set. */
+    placeholder: string;
+    /**
+     * How the trigger is ANNOUNCED: its own name, and the window it holds. The
+     * name has to carry the window, because a button whose `aria-label` is
+     * "Time window" says nothing about the seven days it is currently showing.
+     */
+    triggerName: (name: string, window: string) => string;
+    /** Names the rail of relative windows. */
+    presetsLabel: string;
+    /** Names the absolute side. */
+    absoluteLabel: string;
+    timezoneLabel: string;
+    localLabel: string;
+    utcLabel: string;
+    startLabel: string;
+    endLabel: string;
+    startDateLabel: string;
+    startTimeLabel: string;
+    endDateLabel: string;
+    endTimeLabel: string;
+    previousMonthLabel: string;
+    nextMonthLabel: string;
+    customLabel: string;
+    customAmountLabel: string;
+    customUnitLabel: string;
+    /** What a unit is called in the custom row's chooser. */
+    unitNames: Record<TimeWindowUnit, string>;
+    /** What a calendar span is called where no preset names it. */
+    spanNames: Record<TimeWindowSpan, string>;
+    /** What a duration no preset names is called: "Last 3 days". */
+    durationWindow: (amount: number, unit: TimeWindowUnit) => string;
+    /** Two moments, as one phrase. */
+    range: (from: string, to: string) => string;
+    /** The open end of a relative window. */
+    nowLabel: string;
+    /** The open start of a window with only an end. */
+    earliestLabel: string;
+    /** A window that narrows nothing. */
+    unsetLabel: string;
+    /** The window and what it resolves to, as one sentence. */
+    summary: (window: string, range: string) => string;
+    resetLabel: string;
+    cancelLabel: string;
+    applyLabel: string;
+}
+export type TimeWindowUnit = 'm' | 'h' | 'd' | 'w';
+export interface TimeWindowPickerProps {
+    value: TimeWindowValue;
+    onChange: (value: TimeWindowValue) => void;
+    /**
+     * The window Reset goes back to. Without one there is nothing to go back
+     * TO, so the control is not drawn: a Reset that clears the window to
+     * nothing is a different button wearing the same word.
+     */
+    defaultValue?: TimeWindowValue | undefined;
+    /**
+     * The windows this caller can actually answer, in the order a reader reads
+     * them. A screen whose store keeps thirty days offers thirty days, and
+     * nothing offers a year that comes back empty with no explanation.
+     */
+    presets?: readonly TimeWindowPreset[] | undefined;
+    /** Suppress the rail of relative windows. */
+    allowRelative?: boolean | undefined;
+    /** Suppress the absolute side. */
+    allowAbsolute?: boolean | undefined;
+    /** Suppress the row that takes a relative window the rail does not offer. */
+    allowCustom?: boolean | undefined;
+    /** The days a reader may choose between. */
+    bounds?: TimeWindowBounds | undefined;
+    /** 0 is Sunday (the United States), 1 is Monday (ISO 8601). */
+    firstDayOfWeek?: 0 | 1 | undefined;
+    /** Names the trigger and the dialog it opens. */
+    ariaLabel?: string | undefined;
+    className?: string | undefined;
+    disabled?: boolean | undefined;
+    size?: 'sm' | 'md' | undefined;
+    /** Every string the picker renders on its own. */
+    labels?: Partial<TimeWindowLabels> | undefined;
+}
+/** The length of a `15m`, `1h`, `7d` duration in milliseconds, or 0 for anything else. */
+export declare function parseTimeWindowDuration(text: string): number;
+/**
+ * What a window means right now, as two ISO instants.
+ *
+ * `now` is a parameter rather than a read of the clock so that a caller can
+ * resolve a window against the same moment it resolved another one against,
+ * and so that the panel's own arithmetic does not move underneath a reader
+ * while they are using it.
+ */
+export declare function resolveTimeWindow(value: TimeWindowValue, now?: Date): {
+    from: string | undefined;
+    to: string | undefined;
+};
+export declare const DEFAULT_TIME_WINDOW_LABELS: TimeWindowLabels;
+/** What a window IS, said three ways, for the three places that have to say it. */
+export interface TimeWindowDescription {
+    /** What the window is CALLED: "Last 7 days", "Today", or two moments. */
+    window: string;
+    /** What it resolves to right now: "Sep 8, 2026, 09:41 to now". */
+    range: string;
+    /** Both, as one sentence. This is what a screen reader is given. */
+    spoken: string;
+}
+export interface TimeWindowDescribeOptions {
+    /** The names this caller offers, so a window is called what its own rail calls it. */
+    presets?: readonly TimeWindowPreset[] | undefined;
+    labels?: Partial<TimeWindowLabels> | undefined;
+    /** The moment the window resolves against. */
+    now?: Date | undefined;
+}
+/**
+ * Whether a value and a preset mean the same window.
+ *
+ * A duration is compared by its LENGTH rather than by its spelling, so a
+ * window somebody stored as `1d` is named by the rail's own `24h` row instead
+ * of falling through to a second phrase for exactly the same window.
+ */
+export declare function timeWindowMatchesPreset(value: TimeWindowValue, preset: TimeWindowPreset): boolean;
+/** Whether a window narrows anything at all. */
+export declare function isTimeWindowSet(value: TimeWindowValue): boolean;
+/**
+ * What is selected, in words.
+ *
+ * ONE IMPLEMENTATION, because three surfaces have to agree about it: the
+ * trigger draws it, the trigger's accessible NAME carries it (a button named
+ * only "Time window" tells a screen reader nothing about the seven days it is
+ * showing), and the panel states it as the draft moves. Written per surface,
+ * the three drifted the moment a preset was renamed.
+ */
+export declare function describeTimeWindow(value: TimeWindowValue, options?: TimeWindowDescribeOptions): TimeWindowDescription;
+/**
+ * A window of time: one of the windows a reader asks for by name, or two
+ * moments.
+ *
+ * THE PANEL IS ONE SURFACE, not two tabs. It used to be an Absolute tab and a
+ * Relative tab, with the relative one a grid of BARE NUMBERS under unit
+ * headings: "Last 7 days" was a 7 in a row called Days, and reaching it meant
+ * switching tab first. What a reader wants is almost always one of six or
+ * eight named windows, so those are a rail down the side of the panel, always
+ * on screen, with the calendar beside them rather than behind them.
+ *
+ * THE TWO SIDES SAY THE SAME THING. Take "Last 7 days" and the calendar shades
+ * those seven days and the boxes fill with the moments they resolve to; edit a
+ * box or take a day and the window becomes that absolute range and the rail
+ * lets go. There is one window, drawn twice, rather than two windows the panel
+ * has to choose between when Apply is pressed.
+ *
+ * WHAT IS SELECTED IS SAID OUT LOUD, in one place ([describeTimeWindow]) that
+ * the trigger's text, the trigger's accessible NAME and the panel's own live
+ * line all read from. The trigger used to carry `aria-label="Time window"`
+ * over its own text, so the one thing it was drawn to say -- which window is
+ * on -- was the one thing a screen reader could not hear from it.
+ *
+ * AND THERE IS A WAY BACK. `defaultValue` is the window the screen opens on,
+ * and Reset returns the draft to it; without one the control is not drawn,
+ * because a Reset with nothing to reset to is a Clear wearing the wrong word.
+ *
+ * The draft, the masked boxes and the two-month grid are unchanged: a partial
+ * date still rolls back rather than travelling, the mask letters are still a
+ * picture nobody hears, and the calendar is still the shared [CalendarGrid],
+ * so the same keyboard works here as in every other picker.
+ */
+export declare function TimeWindowPicker({ value, onChange, defaultValue, presets, allowRelative, allowAbsolute, allowCustom, bounds, firstDayOfWeek, ariaLabel, className, disabled, size, labels: labelOverrides, }: TimeWindowPickerProps): import("react/jsx-runtime").JSX.Element;

package/dist/TimeWindowPicker/index.d.ts

@@ -0,0 +1,3 @@
+import './TimeWindowPicker.css';
+export { DEFAULT_TIME_WINDOW_LABELS, TIME_WINDOW_SPANS, TimeWindowPicker, describeTimeWindow, isTimeWindowSet, timeWindowMatchesPreset, parseTimeWindowDuration, resolveTimeWindow, } from './TimeWindowPicker.js';
+export type { TimeWindowBounds, TimeWindowDescribeOptions, TimeWindowDescription, TimeWindowLabels, TimeWindowMode, TimeWindowPickerProps, TimeWindowPreset, TimeWindowSpan, TimeWindowTimezone, TimeWindowUnit, TimeWindowValue, } from './TimeWindowPicker.js';

package/dist/TimeWindowPicker/index.js

@@ -0,0 +1,13 @@
+export { DEFAULT_TIME_WINDOW_LABELS, TIME_WINDOW_SPANS, TimeWindowPicker, describeTimeWindow, isTimeWindowSet, parseTimeWindowDuration, resolveTimeWindow, timeWindowMatchesPreset } from '../chunk-G2QFRTJ2.js';
+import '../chunk-5IMACPJS.js';
+import '../chunk-DD5BBGBE.js';
+import '../chunk-GXQ3B46I.js';
+import '../chunk-GTOUGQQK.js';
+import '../chunk-O6232G37.js';
+import '../chunk-PQADV6P6.js';
+import '../chunk-7RPGY3JE.js';
+import '../chunk-ITHXJHBB.js';
+import '../chunk-F27EPQ7D.js';
+import '../chunk-BZYDZBAN.js';
+import '../chunk-BZFWDIV6.js';
+import '../chunk-ODEQTPFM.js';

package/dist/TimeWindowPicker/mask.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The grammar behind the masked date and time boxes.
+ *
+ * Kept beside the component rather than inside it because every rule here is
+ * a decision about what a date IS, and each one was wrong in a way no test
+ * could see: a year capped at 2030, a February with 31 days in it, and an
+ * hour of 24 followed by 60 minutes and 60 seconds.
+ */
+/** One numeric run inside a mask: where it sits, and what it may hold. */
+export interface MaskSegment {
+    /** First mask position in the run, inclusive. */
+    start: number;
+    /** Last mask position in the run, inclusive. */
+    end: number;
+    min: number;
+    max: number;
+}
+export declare const DATE_MASK = "YYYY/MM/DD";
+export declare const TIME_MASK = "HH:MM:SS";
+/**
+ * The date segments.
+ *
+ * THE YEAR HAS NO CEILING WORTH SPELLING. It was 2000 to 2030, which is a
+ * ceiling that arrives: on the first of January 2031 the field stops
+ * accepting the current year, and it does it by refusing the keystroke, so
+ * there is nothing on screen to say why. Four digits is the only real
+ * constraint a four-digit field has.
+ */
+export declare const DATE_SEGMENTS: readonly MaskSegment[];
+/**
+ * The time segments.
+ *
+ * AN HOUR IS 0 TO 23 AND A MINUTE IS 0 TO 59. The ranges were 00 to 24 and 00
+ * to 60, so "24:60:60" was accepted, handed to `Date`, and silently became
+ * one o'clock the following morning: a window a reader set to the end of a
+ * day quietly started the next one.
+ */
+export declare const TIME_SEGMENTS: readonly MaskSegment[];
+/** Whether the character at `position` of a mask is a separator rather than a slot. */
+export declare const isSeparator: (mask: string, position: number) => boolean;
+/** How many digits a mask holds. */
+export declare const slotCount: (mask: string) => number;
+/**
+ * The digits of `text`, laid into the mask with its separators between them.
+ *
+ * SEPARATORS GO BETWEEN DIGITS, never after the last one. Appended eagerly,
+ * "2026" becomes "2026/" and Backspace can never get back past it: the key
+ * removes the separator, the projection puts it straight back, and the year
+ * cannot be corrected without clearing the whole field.
+ */
+export declare function project(mask: string, text: string): string;
+/** The mask letters still unfilled, which the overlay draws after the value. */
+export declare function remainder(mask: string, text: string): string;
+/** Whether `text` fills every slot in the mask. */
+export declare const isComplete: (mask: string, text: string) => boolean;
+/**
+ * Whether a filled date is a date that exists.
+ *
+ * BY ROUND TRIP, not by range. The ranges say 01 to 12 and 01 to 31, and
+ * every one of 31 February, 31 April and 29 February 2027 passes all three:
+ * `Date` takes them and rolls them forward into the next month, so a reader
+ * who typed one got a window starting on a day they never chose. Building the
+ * date and asking it what it became is the only check that catches that.
+ */
+export declare function isRealDate(text: string): boolean;
+/** Whether a filled time is a time that exists. 24:60:60 is not one. */
+export declare function isRealTime(text: string): boolean;
+/**
+ * The segment the caret at `position` sits in, or the last one it passed.
+ *
+ * The caret can rest just after a run's final digit, before the separator, so
+ * a segment owns one position past its own end.
+ */
+export declare function segmentAt(segments: readonly MaskSegment[], position: number): MaskSegment | undefined;
+/**
+ * `text` with one segment stepped by `by`, clamped to its own range.
+ *
+ * A segment with no digits in it yet is SEEDED with its minimum rather than
+ * stepped from nothing, so a reader can spin a date up from an empty field.
+ * A segment after an empty one is left alone: there is nothing to step into.
+ */
+export declare function stepSegment(mask: string, text: string, segment: MaskSegment, by: 1 | -1): string;