# API of `@koobiq/components/time-range`

Documented on [Time range](https://koobiq.io/en/components/time-range.md). NgModule: `KbqTimeRangeModule`.

## Components

### KbqTimeRange (component)

```ts
@Component({ selector: 'kbq-time-range' })
class KbqTimeRange<T> implements ControlValueAccessor {
    readonly minDate = input<T>();
    readonly maxDate = input<T>();
    readonly defaultRangeValue = input<KbqRangeValue<T>>();
    readonly availableTimeRangeTypes = input<KbqTimeRangeType[]>(
        this.timeRangeService.providedDefaultTimeRangeTypes
    );
    readonly titleTemplate = input<TemplateRef<KbqTimeRangeCustomizableTitleContext>>();
    readonly optionTemplate = input<TemplateRef<KbqTimeRangeOptionContext>>();
    readonly arrow = input<boolean>(true);
    readonly showRangeAsDefault = input<boolean>(true);
    readonly nonNullable = input<boolean>(true);
    readonly valueCorrected = output<KbqTimeRangeRange>();
    readonly value: Signal<KbqTimeRangeRange | null>;
    readonly disabled: Signal<boolean>;
    onVisibleChange(isVisible: boolean): void;
}
```

- `[minDate]`: `T` — The earliest date the calendars offer and the validation accepts.
- `[maxDate]`: `T` — The latest date the calendars offer and the validation accepts.
- `[defaultRangeValue]`: `KbqRangeValue<T>` — Seeds the from/to pair of the manual range.
- `[availableTimeRangeTypes]`: `KbqTimeRangeType[]` — The options the editor offers, in order. The first one is selected by default.
- `[titleTemplate]`: `TemplateRef<KbqTimeRangeCustomizableTitleContext>` — Replaces the built-in trigger.
- `[optionTemplate]`: `TemplateRef<KbqTimeRangeOptionContext>` — Replaces the built-in rendering of an option in the editor.
- `[arrow]`: `boolean` — Whether the popover is drawn with an arrow.
- `[showRangeAsDefault]`: `boolean` — Keeps the manual range visible even when `range` is not in `availableTimeRangeTypes`.
- `[nonNullable]`: `boolean` — Falls back to a default value instead of holding `null`.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `(valueCorrected)`: `KbqTimeRangeRange` — Emits the corrected value when the provided one could not be used as is.
- `value`: `Signal<KbqTimeRangeRange | null>` — The applied time range, or `null` when the component is nullable and holds no value.

  This is what the trigger renders, so it lags the editor until Apply.
- `disabled`: `Signal<boolean>` — Whether the control is disabled through the forms layer.

### KbqTimeRangeTitleAsControl (component)

Component simulates `KbqFormFieldControl` allowing to provide custom content inside `KbqFormField`

```ts
@Component({ selector: 'kbq-time-range-title-as-control' })
class KbqTimeRangeTitleAsControl implements KbqFormFieldControl<KbqTimeRangeRange> {}
```

## Directives

### KbqTimeRangeTitlePlaceholder (directive)

Directive for easy using styles of time-range placeholder publicly.

```ts
@Directive({ selector: '[kbqTimeRangeTitlePlaceholder]' })
class KbqTimeRangeTitlePlaceholder {}
```

## Types

### KbqCustomTimeRangeType (type)

```ts
type KbqCustomTimeRangeType = {
    type: KbqTimeRangeType | string;
    units: KbqTimeRangeUnits;
    translationType: KbqTimeRangeTranslationType;
    range?: KbqRange;
};
```

- `type`: `KbqTimeRangeType | string` — time range identifier. Used as config key
- `units`: `KbqTimeRangeUnits` — Duration metadata
- `translationType`: `KbqTimeRangeTranslationType` — Property representing duration output unit
- `range?`: `KbqRange` — Custom range of start/end date-times

### KbqRange (type)

Represents a time range with optional start and end date-time values.
Used as a range value by default.

```ts
type KbqRange = {
    startDateTime?: string;
    endDateTime?: string;
};
```

### KbqRangeValue (interface)

Represents a time range with optional start and end date-time values.
Used as a form value when range in popover change.

```ts
interface KbqRangeValue<T> {
    fromTime?: T;
    fromDate?: T;
    toTime?: T;
    toDate?: T;
}
```

### KbqTimeRangeCustomizableTitleContext (type)

Context for a time range trigger customization, combining meta information.

```ts
type KbqTimeRangeCustomizableTitleContext = Partial<KbqTimeRangeTitleContext> & {
    $implicit: Partial<KbqTimeRangeTitleContext> & { formattedDate: string; popover: KbqPopoverTrigger };
} & { formattedDate: string; popover: KbqPopoverTrigger };
```

### KbqTimeRangeOptionContext (type)

Context for a time range option customization, combining meta information.

```ts
type KbqTimeRangeOptionContext = KbqTimeRangeTypeContext & KbqTimeRangeUnits & {
    translationType: KbqTimeRangeTranslationType;
    formattedValue: string;
};
```

### KbqTimeRangeRange (type)

Main range information.
Used for a popover date range selection, when selected type is range,
and for trigger information calculation.

```ts
type KbqTimeRangeRange = KbqRange & KbqTimeRangeTypeContext;
```

### KbqTimeRangeTitleContext (type)

Context for a time range trigger, combining range info and type.

```ts
type KbqTimeRangeTitleContext = KbqTimeRangeRange & KbqTimeRangeUnits;
```

### KbqTimeRangeTranslationType (type)

Property representing duration output unit

```ts
type KbqTimeRangeTranslationType = Exclude<DurationUnit, 'quarters' | 'milliseconds'> | 'other';
```

### KbqTimeRangeType (type)

Default accepted “time‑range” identifiers.

```ts
type KbqTimeRangeType = | 'lastMinute'
    | 'last5Minutes'
    | 'last15Minutes'
    | 'last30Minutes'
    | 'lastHour'
    | 'last24Hours'
    | 'last3Days'
    | 'last7Days'
    | 'last14Days'
    | 'last30Days'
    | 'last3Months'
    | 'last12Months'
    | 'allTime'
    | 'currentQuarter'
    | 'currentYear'
    | 'range';
```

### KbqTimeRangeTypeContext (type)

Range type selected

```ts
type KbqTimeRangeTypeContext = {
    type: KbqTimeRangeType;
};
```

### KbqTimeRangeUnits (interface)

Configuration for a custom time range with duration metadata.
Defines a time range with its identifier, duration units, and optional fixed date range.

```ts
interface KbqTimeRangeUnits extends DurationObjectUnits {
    years?: number;
    quarters?: number;
    months?: number;
    weeks?: number;
    days?: number;
    hours?: number;
    minutes?: number;
    seconds?: number;
    milliseconds?: number;
}
```

## Constants

### defaultTimeRangeTypes (const)

Time range types in range editor if nothing provided

```ts
const defaultTimeRangeTypes: KbqTimeRangeType[];
```

### KBQ_CUSTOM_TIME_RANGE_TYPES (const)

Preset of custom time ranges, provided by DI.

```ts
const KBQ_CUSTOM_TIME_RANGE_TYPES: InjectionToken<KbqCustomTimeRangeType[]>;
```

### KBQ_DEFAULT_TIME_RANGE_TYPES (const)

Preset of selectable time ranges, provided by DI.

```ts
const KBQ_DEFAULT_TIME_RANGE_TYPES: InjectionToken<KbqTimeRangeType[]>;
```

### KBQ_TIME_RANGE_LOCALE_CONFIGURATION (const)

Localization configuration provider.

```ts
const KBQ_TIME_RANGE_LOCALE_CONFIGURATION: InjectionToken<KbqTimeRangeLocaleConfiguration>;
```

### kbqTimeRangeLocaleConfigurationProvider (const)

Utility provider for `KBQ_TIME_RANGE_LOCALE_CONFIGURATION`. Only the strings you pass are overridden;
the rest keep following the active locale.

```ts
const kbqTimeRangeLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqTimeRangeLocaleConfiguration>
) => Provider;
```

### rangeValidator (const)

Validates that the 'from' date-time is not greater than the 'to' date-time in a range form.
Returns an error if the start date-time occurs after the end date-time.

```ts
const rangeValidator: <T>(
    timeRangeService: KbqTimeRangeService<T>
) => ValidatorFn;
```
