@koobiq/components 20.3.0 → 20.3.2

package/time-range/index.d.ts

@@ -1,6 +1,6 @@
 import * as _angular_core from '@angular/core';
-import { InjectionToken, OnInit, TemplateRef, WritableSignal, Provider, Injector } from '@angular/core';
-import { ValidatorFn, ControlValueAccessor, NgControl, FormControl, Validator, FormGroup, AbstractControl, FormGroupDirective, NgForm, ValidationErrors } from '@angular/forms';
+import { Signal, InjectionToken, OnInit, TemplateRef, WritableSignal, Provider, Injector } from '@angular/core';
+import { ValidatorFn, ControlValueAccessor, NgControl, FormControl, Validator, FormGroup, AbstractControl, ValidationErrors } from '@angular/forms';
 import { DateAdapter, DateFormatter, KbqTimeRangeLocaleConfig, PopUpSizes, PopUpPlacements, ErrorStateMatcher } from '@koobiq/components/core';
 import { KbqPopoverTrigger } from '@koobiq/components/popover';
 import { DurationObjectUnits, DurationUnit } from '@koobiq/date-adapter';
@@ -82,18 +82,47 @@ declare class KbqTimeRangeService<T> {
     readonly providedDefaultTimeRangeTypes: KbqTimeRangeType[];
     readonly customTimeRangeTypes: KbqCustomTimeRangeType[] | null;
     readonly DEFAULT_RANGE_TYPE: KbqTimeRangeType;
+    private readonly boundsSource;
+    /**
+     * Bounds of the owning component, so that every default and every check reads one pair. Both are
+     * exact instants rather than whole days: a `maxDate` that should admit its own day has to carry the
+     * end of that day.
+     */
+    readonly minDate: Signal<NonNullable<T> | null>;
+    /** @see minDate */
+    readonly maxDate: Signal<NonNullable<T> | null>;
     readonly timeRangeConfig: Record<KbqTimeRangeType, Omit<KbqCustomTimeRangeType, 'type'>>;
     constructor();
     static range: (dateTimeISOString: string) => KbqRange;
     add({ type, ...customTimeRangeConfig }: KbqCustomTimeRangeType): void;
+    /**
+     * Hands the owning component's own bound inputs over, rather than a copy of their values: a signal
+     * input reads as its initial value until the first change detection, so a mirror would leave every
+     * default computed in a constructor clamped against no bounds at all.
+     */
+    bindBounds(min: Signal<T | null | undefined>, max: Signal<T | null | undefined>): void;
     getTimeRangeTypeUnits(type: KbqTimeRangeType): KbqTimeRangeUnits;
     getTimeRangeUnitByType(type: KbqTimeRangeType): KbqTimeRangeTranslationType;
+    /**
+     * "Yesterday to today", pulled inside {@link minDate}/{@link maxDate} when they are set - otherwise
+     * the editor opens on a range it would itself report as out of bounds.
+     *
+     * Milliseconds are dropped from "today" *before* clamping, so a clamped end lands exactly on its
+     * bound rather than a fraction of a second below it.
+     */
     getDefaultRangeValue(): Required<KbqRangeValue<T>>;
     getTimeRangeDefaultValue(rangeValue: KbqRangeValue<T>, availableTimeRangeTypes?: KbqTimeRangeType[]): KbqTimeRangeRange;
     calculateTimeRange(type?: KbqTimeRangeType, rangeValue?: KbqRangeValue<T>): KbqRange;
     combineDateAndTime(date: T, time: T): T;
     lastUnitsRange: (unitsInfo: KbqTimeRangeUnits) => KbqRange;
     checkAndCorrectTimeRangeValue(value: KbqTimeRangeRange | null | undefined, availableTimeRangeTypes: KbqTimeRangeType[], rangeValue: KbqRangeValue<T>): KbqTimeRangeRange;
+    /** Which bound, if any, an instant falls outside of. */
+    private checkBounds;
+    /**
+     * `DateAdapter.clampDate` compares whole days only, while a border is rejected by its time as well -
+     * a value clamped to the day would still land outside the bounds.
+     */
+    private clampToBounds;
     omitMilliseconds(date: T): T;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<KbqTimeRangeService<any>, never>;
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<KbqTimeRangeService<any>>;
@@ -122,6 +151,8 @@ declare const kbqTimeRangeLocaleConfigurationProvider: (configuration: KbqTimeRa
 declare class KbqTimeRange<T> implements ControlValueAccessor, OnInit {
     private readonly timeRangeService;
     private readonly localeService;
+    private readonly editorBridge;
+    private readonly document;
     /** @docs-private */
     readonly ngControl: NgControl | null;
     /** The minimum selectable date. */
@@ -170,7 +201,17 @@ declare class KbqTimeRange<T> implements ControlValueAccessor, OnInit {
     ngOnInit(): void;
     /** Implemented as part of ControlValueAccessor */
     writeValue(value: KbqTimeRangeRange | null): void;
-    /** @docs-private */
+    /**
+     * Lets the editor tell an "apply" gesture from a plain focus loss before the click even lands - the
+     * `focusout` it reacts to is dispatched between this `mousedown` and the `click` below.
+     * @docs-private
+     */
+    protected onFooterPointerDown(): void;
+    /**
+     * Applying is always offered; an invalid editor keeps the popover open and sends the user to the
+     * first field at fault instead.
+     * @docs-private
+     */
     onApply(popover: KbqPopoverTrigger): void;
     /** @docs-private */
     onCancel(popover: KbqPopoverTrigger): void;
@@ -183,6 +224,8 @@ declare class KbqTimeRange<T> implements ControlValueAccessor, OnInit {
     registerOnChange(fn: (_value: KbqTimeRangeRange) => void): void;
     /** Implemented as part of ControlValueAccessor */
     registerOnTouched(fn: () => void): void;
+    /** What the editor opens on: the first offered type, or a plain range when none are offered. */
+    private defaultEditorValue;
     private handleAvailableTypesChange;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<KbqTimeRange<any>, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<KbqTimeRange<any>, "kbq-time-range", never, { "minDate": { "alias": "minDate"; "required": false; "isSignal": true; }; "maxDate": { "alias": "maxDate"; "required": false; "isSignal": true; }; "defaultRangeValue": { "alias": "defaultRangeValue"; "required": false; "isSignal": true; }; "availableTimeRangeTypes": { "alias": "availableTimeRangeTypes"; "required": false; "isSignal": true; }; "titleTemplate": { "alias": "titleTemplate"; "required": false; "isSignal": true; }; "optionTemplate": { "alias": "optionTemplate"; "required": false; "isSignal": true; }; "arrow": { "alias": "arrow"; "required": false; "isSignal": true; }; "showRangeAsDefault": { "alias": "showRangeAsDefault"; "required": false; "isSignal": true; }; "nonNullable": { "alias": "nonNullable"; "required": false; "isSignal": true; }; }, { "valueCorrected": "valueCorrected"; }, never, never, true, never>;
@@ -210,12 +253,22 @@ interface FormValue<T> {
     toTime: FormControl<T>;
     toDate: FormControl<T>;
 }
+/** One end of the range. Its date and its time are checked together, and revealed together. */
+type RangeBorder = 'from' | 'to';
+/**
+ * Errors are reported only once the user has left the border they belong to, and go quiet again as soon
+ * as typing resumes. The validators themselves always run, so that `validate()` stays honest about
+ * whether the range could be saved - only the painting waits.
+ */
 declare class RangeErrorStateMatcher implements ErrorStateMatcher {
-    isErrorState(control: AbstractControl | null, form: FormGroupDirective | NgForm | null): boolean;
+    isErrorState(control: AbstractControl | null): boolean;
 }
 /** @docs-private */
 declare class KbqTimeRangeEditor<T> implements ControlValueAccessor, Validator, OnInit {
     private readonly timeRangeService;
+    private readonly editorBridge;
+    private readonly elementRef;
+    private readonly document;
     /** The maximum selectable date. */
     readonly maxDate: _angular_core.InputSignal<T | null>;
     /** The minimum selectable date. */
@@ -232,15 +285,32 @@ declare class KbqTimeRangeEditor<T> implements ControlValueAccessor, Validator,
     protected readonly isRangeVisible: _angular_core.Signal<boolean>;
     /** @docs-private */
     protected readonly timeRangeTypesWithoutRange: _angular_core.Signal<KbqTimeRangeOptionContext[]>;
+    /**
+     * Caption under the "range" option, spelling out the bounds the border has to stay within. Read from
+     * the service rather than from this component's own inputs, so that it can never disagree with what
+     * the border validators go on to enforce.
+     * @docs-private
+     */
+    protected readonly boundsHint: _angular_core.Signal<string>;
     /** @docs-private */
     protected readonly timepickerList: _angular_core.Signal<readonly KbqTimepicker<T>[]>;
     /** @docs-private */
     protected readonly form: FormGroup<FormValue<T>>;
+    /**
+     * The same four controls as `form`, indexed as two ends each with a date and a time. The form itself
+     * has to stay flat, because its value is the `KbqRangeValue` the service and the bound control speak
+     * in - this is the single place the two shapes are tied together, and `Record` over both dimensions is
+     * what keeps it exhaustive.
+     */
+    private readonly borderControls;
+    /** The same four, flat, for the checks that treat the range as one thing. */
+    private readonly rangeControls;
     /** @docs-private */
     protected readonly timepickerFormat = TimeFormats.HHmmss;
     /** @docs-private */
     protected readonly rangeStateMatcher: RangeErrorStateMatcher;
-    private lastValidationErrorOnEmit;
+    /** Raised by the first "apply", after which a border left wholly empty counts as an error too. */
+    private applyAttempted;
     constructor();
     ngOnInit(): void;
     /** @docs-private */
@@ -255,6 +325,71 @@ declare class KbqTimeRangeEditor<T> implements ControlValueAccessor, Validator,
     registerOnChange(fn: (value: KbqTimeRangeRange) => void): void;
     /** Implemented as part of ControlValueAccessor */
     registerOnTouched(fn: () => void): void;
+    /**
+     * Leaving one border reports what is wrong with it. Angular marks a control touched on its own blur,
+     * which is a finer grain than the spec asks for - so moving between a border's own date and time
+     * takes the touch back off, and the pair is judged only once focus is out of both.
+     * @docs-private
+     */
+    protected onBorderFocusOut(border: RangeBorder, { currentTarget, relatedTarget }: FocusEvent): void;
+    /**
+     * Typing puts a border back to its neutral state, the way `validation-on-blur` does for a single
+     * field. What is wrong with it is said again when focus leaves it.
+     * @docs-private
+     */
+    protected onBorderInput(border: RangeBorder): void;
+    /**
+     * What is said when the range as a whole has left the bounds. Said once, below the last of the two
+     * ends, and only when both of them are at fault: a single end out of bounds is already pointed at by
+     * the fields painted around it. Silent until the ends have been left, keeping step with that
+     * painting.
+     * @docs-private
+     */
+    protected outOfBoundsMessage(): string;
+    /**
+     * Once focus leaves the manual range fields, a reversed range is silently swapped back into order -
+     * except on the way to "apply", where the swap is left to the emitted value so that the popover does
+     * not visibly reorder itself in the same gesture that closes it.
+     * @docs-private
+     */
+    protected onRangeFocusOut({ currentTarget, relatedTarget }: FocusEvent): void;
+    /**
+     * Reveals both borders and sends the user to the first field at fault, reporting whether there is
+     * anything to fix at all.
+     */
+    private revealErrors;
+    /** Whether a bound is a moment within its day rather than the day itself. */
+    private carriesTime;
+    /** Whether focus is still inside `group`, counting the datepicker calendar as part of it. */
+    private staysWithin;
+    /** Both halves of a border are painted, or neither: the pair is what the user is judged on. */
+    private setBorderTouched;
+    /** Both halves of one end, in the order they are painted. */
+    private borderHalves;
+    /** Each half is checked against its sibling, so a change to one has to re-run the other. */
+    private revalidateRange;
+    private swapIfReversed;
+    /**
+     * Whether anything about the borders would stop the range being saved. Deliberately blind to which
+     * borders have been revealed: a swap rewrites the user's values, so it has to answer "is this range
+     * actually sound", not "has the user been shown the problem yet".
+     */
+    private hasBorderProblem;
+    /**
+     * What is wrong with each half of a border, whether or not the user has been shown it. A missing half
+     * is flagged on its own; a bound is judged in two steps, so that the field actually at fault is the
+     * one painted.
+     */
+    private borderErrors;
+    /** Which bound a border falls outside of, and whether its day or only its time is to blame. */
+    private checkBorderBounds;
+    private isReversed;
+    /**
+     * A border reports only what the pickers do not: an empty half next to a filled one, a border left
+     * wholly empty once "apply" was pressed, and a border outside the bounds. Format is the pickers' own
+     * business, and so is the calendar restriction.
+     */
+    private borderValidator;
     private mapTimeRange;
     private getFormattedOption;
     private concatControlValidationErrors;

package/time-range/time-range.scss

@@ -40,9 +40,24 @@
             gap: var(--kbq-size-s);
 
             .kbq-time-range-editor__date-time-prefix {
-                align-self: center;
+                // The label names the fields, not the caption or the error message below them, so it is
+                // centred on the row of fields alone. Centring it on the whole block would drop it as
+                // soon as the fieldset grows downwards.
+                display: flex;
+                align-items: center;
+                align-self: flex-start;
+                min-height: var(--kbq-size-3xl);
+                flex: none;
                 width: 57px;
             }
+
+            // Sized by the row rather than by what it holds: the caption and the error message are wider
+            // than the fields, and an intrinsically sized fieldset would leave the two rows a few pixels
+            // apart from each other.
+            .kbq-fieldset {
+                flex: 1;
+                min-width: 0;
+            }
         }
     }
 }

package/title/index.d.ts

@@ -12,7 +12,8 @@ import { Subject } from 'rxjs';
  * By default, the tooltip content is the trimmed `textContent` of the host. Provide explicit content
  * with `[kbq-title]="stringOrTemplateRef"`. For nested markup, mark the measured container with the
  * `#kbqTitleContainer` template reference and the text element(s) with `#kbqTitleText`; several
- * `#kbqTitleText` elements are supported and the tooltip is shown when any of them overflows.
+ * `#kbqTitleText` elements are supported and the tooltip is shown when any of them overflows the container
+ * or is clipped by its siblings.
  *
  * Host components that provide `KBQ_TITLE_TEXT_REF` (e.g. `KbqOption`) supply the text and parent
  * elements automatically, so the directive works without explicit template references.
@@ -42,7 +43,8 @@ declare class KbqTitleDirective extends KbqTooltipTrigger implements AfterViewIn
     /**
      * Whether the host content is clipped and therefore needs a tooltip. Returns `true` if any measured
      * text element overflows the parent — covering multiple `#kbqTitleText` elements, the sub-pixel
-     * special case, and both horizontal and vertical overflow.
+     * special case, and both horizontal and vertical overflow — or, with several text elements, if one of
+     * them clips its own content.
      */
     get isOverflown(): boolean;
     /** Whether the text is clipped horizontally: the parent `offsetWidth` is smaller than the child `scrollWidth`. */
@@ -118,6 +120,12 @@ declare class KbqTitleDirective extends KbqTooltipTrigger implements AfterViewIn
     /** Always disables (hides) the tooltip. Bound to `mouseleave` and non-keyboard focus changes.
      * @docs-private */
     hideTooltip(): void;
+    /**
+     * Whether a text element is narrower than its own text. Text elements that share the parent can take width
+     * from each other, so one is clipped while its full text would still fit the parent — which the parent
+     * comparison above cannot see. An inline element reports a zero `clientWidth` and never clips.
+     * @docs-private */
+    private isClippedInOwnBox;
     static ɵfac: i0.ɵɵFactoryDeclaration<KbqTitleDirective, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<KbqTitleDirective, "[kbq-title]", ["kbqTitle"], { "titleContent": { "alias": "kbq-title"; "required": false; "isSignal": true; }; }, {}, ["parentContainer", "childContainer"], never, true, never>;
 }

package/tree/index.d.ts

@@ -499,6 +499,7 @@ declare class KbqTreeOptionChange {
 declare class KbqTreeOption extends KbqTreeNode<KbqTreeOption> implements AfterContentInit, KbqTitleTextRef {
     private changeDetectorRef;
     private ngZone;
+    private readonly destroyRef;
     tree: any;
     readonly onFocus: Subject<KbqTreeOptionEvent>;
     readonly onBlur: Subject<KbqTreeOptionEvent>;