@koobiq/components 20.1.0 → 20.3.0

package/core/option/_action-container-mixins.scss

@@ -0,0 +1,28 @@
+/// Decides when the trailing `<kbq-option-action>` of an option becomes visible.
+///
+/// `.kbq-action-container` is `display: none` by default (see `action-container.scss`),
+/// so this mixin is the single source of truth for the reveal rules shared by
+/// `kbq-list-option` and `kbq-tree-option`. Include it inside the option's own rule.
+///
+/// @param {String} $keyboard-focused-host - selector of the focus-monitored selection host
+///   that CDK's `FocusMonitor` marks with `cdk-keyboard-focused`.
+@mixin kbq-option-action-visibility($keyboard-focused-host) {
+    &:not(.kbq-disabled) {
+        &:hover,
+        &.kbq-hovered,
+        &.kbq-action-button-focused {
+            & .kbq-action-container {
+                display: flex;
+            }
+        }
+    }
+
+    // Roving focus reveals the action only when focus arrived from the keyboard.
+    // `.kbq-focused` alone is not enough: options are `tabindex="-1"`, so a mouse click
+    // focuses them too and the action would stay visible after the pointer moves away.
+    #{$keyboard-focused-host} &:not(.kbq-disabled).kbq-focused {
+        & .kbq-action-container {
+            display: flex;
+        }
+    }
+}

package/core/option/_option-theme.scss

@@ -24,18 +24,33 @@
             @include kbq-option(states-hover);
         }
 
+        &:active:not(.kbq-disabled),
+        &.kbq-pressed:not(.kbq-disabled) {
+            // the active state defines only a background token; the mixin would emit undefined text/icon/caption color vars
+            background: var(--kbq-list-states-active-container-background);
+        }
+
         &.kbq-selected:not(.kbq-disabled) {
             @include kbq-option(states-selected);
 
             &.kbq-active {
                 @include kbq-option(states-selected-hover);
             }
+
+            &:active,
+            &.kbq-pressed {
+                background: var(--kbq-list-states-selected-active-container-background);
+            }
         }
 
         &.kbq-disabled {
             @include kbq-option(states-disabled);
         }
 
+        &.kbq-selected.kbq-disabled {
+            background: var(--kbq-list-states-selected-container-background);
+        }
+
         &:is(.kbq-selected, .kbq-active):has(+ :is(.kbq-selected, .kbq-active)) {
             border-bottom-left-radius: 0;
             border-bottom-right-radius: 0;
@@ -54,6 +69,15 @@
             &.kbq-active {
                 @include kbq-option(multiple-states-selected-hover);
             }
+
+            &:active,
+            &.kbq-pressed {
+                background: var(--kbq-list-multiple-states-selected-active-container-background);
+            }
+        }
+
+        &.kbq-selected.kbq-disabled {
+            background: var(--kbq-list-multiple-states-selected-container-background);
         }
     }
 }

package/core/option/action.scss

@@ -11,6 +11,13 @@
 
     outline: none;
 
+    // The transparent border reserves the focus ring, and the size token below is the icon box
+    // without it: 20px + 2 * 2px comes out at the 24px the action actually occupies. Declared so a
+    // global `border-box` reset in a consuming application cannot pull the ring inside and leave the
+    // icon box at 16px. Note that `.kbq-option` next to it uses the same transparent-border trick
+    // the other way round — it is `border-box`, and its 32px is the whole row.
+    box-sizing: content-box;
+
     border: var(--kbq-size-3xs) solid transparent;
     border-radius: var(--kbq-size-xs);
 

package/core/styles/_core.scss

@@ -1,8 +1,10 @@
 @use 'common/overlay' as *;
+@use 'common/connected-overlay' as *;
 @use 'common/visually-hidden' as *;
 
 // Mixin that renders all of the core styles that are not theme-dependent.
 @mixin kbq-core() {
     @include a11y-visually-hidden();
     @include overlay();
+    @include kbq-connected-overlay-gap();
 }

package/core/styles/_koobiq-theme.scss

@@ -11,6 +11,7 @@
 @use '../forms/forms-theme' as *;
 @use '../highlight/highlight-theme' as *;
 
+// @TODO: Argument is unused. will be removed in next major release
 @mixin koobiq-theme($theme: null) {
     @include kbq-core-theme();
 
@@ -25,6 +26,7 @@
     @include kbq-tag-theme();
 }
 
+// @TODO: Argument is unused. will be removed in next major release
 @mixin koobiq-typography($tokens: null, $config: null, $md-config: null) {
     @include kbq-base-typography();
     @include kbq-markdown-base-typography();

package/core/styles/_tokens.scss

@@ -1,5 +1,6 @@
 @use 'sass:color' as *;
 
+// @deprecated @TODO: Will be removed in a future major version.
 @forward '@koobiq/design-tokens/web/variables';
 @forward '@koobiq/design-tokens/web/palette';
 @forward '@koobiq/design-tokens/web/typography';

package/core/styles/common/_animation.scss

@@ -8,34 +8,41 @@
     }
 }
 
+// Renders the striped "loading" shimmer used by .kbq-progress. Extracted into a mixin so
+// components whose `::before`/`::after` pseudo-elements are already spoken for (e.g. kbq-dropdown-item's
+// hit-area extension) can apply the same overlay to a real element instead.
+@mixin kbq-progress-overlay() {
+    content: '';
+    position: absolute;
+    border-radius: inherit;
+
+    top: 0;
+    right: 0;
+    bottom: 0;
+    left: 0;
+
+    $lighter: rgba(255, 255, 255, 0.1);
+    $darker: rgba(0, 0, 0, 0.04);
+
+    background: linear-gradient(
+            135deg,
+            $darker 12px,
+            $lighter 12px,
+            $lighter 22px,
+            $darker 22px,
+            $darker 34px,
+            $lighter 34px
+        )
+        repeat;
+    background-size: 32px 32px;
+    animation: kbq-progress 1s linear infinite;
+}
+
 .kbq-progress {
     position: relative;
 
     &:after {
-        content: '';
-        position: absolute;
-        border-radius: inherit;
-
-        top: 0;
-        right: 0;
-        bottom: 0;
-        left: 0;
-
-        $lighter: rgba(255, 255, 255, 0.1);
-        $darker: rgba(0, 0, 0, 0.04);
-
-        background: linear-gradient(
-                135deg,
-                $darker 12px,
-                $lighter 12px,
-                $lighter 22px,
-                $darker 22px,
-                $darker 34px,
-                $lighter 34px
-            )
-            repeat;
-        background-size: 32px 32px;
-        animation: kbq-progress 1s linear infinite;
+        @include kbq-progress-overlay();
 
         @media (prefers-reduced-motion: reduce) {
             animation: none;

package/core/styles/common/_connected-overlay.scss

@@ -0,0 +1,39 @@
+/// Recreates the trigger↔panel gap for connected dropdown panels as transparent padding
+/// INSIDE the `.cdk-overlay-pane`, instead of a physical overlay `offsetY`.
+
+// Previously the gap was produced by the CDK overlay `offsetY` (`defaultOffsetY`,
+// packages/components/core/pop-up/constants.ts), which shifted the whole pane away from the trigger and
+// left a dead band that was not covered by any overlay element — so the cursor/clicks passed through it
+// onto the content underneath. Now the pane is flush with the trigger (`offsetY: 0`) and the gap is padded
+// inside the pane. Because the pane has `pointer-events: auto`, the band is covered and no longer
+// click/hover-through, while the visible panel keeps the exact same on-screen position.
+
+// The class names must match KBQ_CONNECTED_OVERLAY_BELOW_CLASS / KBQ_CONNECTED_OVERLAY_ABOVE_CLASS /
+// KBQ_CONNECTED_OVERLAY_OVERLAP_CLASS
+// (packages/components/core/pop-up/constants.ts), applied per-position via `ConnectedPosition.panelClass`.
+// The compound `.cdk-overlay-pane.<class>` selector (specificity 0,2,0) deterministically overrides the
+// `.cdk-overlay-pane { padding: 0 }` reset from `overlay()`.
+
+// The gap size is the `--kbq-connected-overlay-gap` custom property, falling back to the `--kbq-size-xxs`
+// token (4px) when unset — so the default is unchanged. The pane is portaled to <body>, so the variable
+// must be set on `:root` or on the pane itself, never on the component that opens it:
+//   * globally:          :root { --kbq-connected-overlay-gap: 8px; }
+//   * per overlay type:  .cdk-overlay-pane.kbq-select-overlay { --kbq-connected-overlay-gap: 8px; }
+
+// Caveat: the `--kbq-size-xxs`/4px default is kept in sync with `defaultOffsetY`
+// (packages/components/core/pop-up/constants.ts), off which components size their viewport-fit compensation
+// (`withViewportMargin`). Enlarging the gap past that can let the pane overflow the viewport edge by
+// `gap - margin`px, so bump the corresponding margin to match.
+@mixin kbq-connected-overlay-gap() {
+    // Panel is below the trigger, or below the first row of a trigger it overlaps: the gap sits at the top
+    // of the pane either way.
+    .cdk-overlay-pane.kbq-connected-overlay_below,
+    .cdk-overlay-pane.kbq-connected-overlay_overlap {
+        padding-top: var(--kbq-connected-overlay-gap, var(--kbq-size-xxs, 4px));
+    }
+
+    // Panel is flipped above the trigger: the gap sits at the bottom of the pane.
+    .cdk-overlay-pane.kbq-connected-overlay_above {
+        padding-bottom: var(--kbq-connected-overlay-gap, var(--kbq-size-xxs, 4px));
+    }
+}

package/core/styles/common/_select.scss

@@ -122,9 +122,16 @@
         overflow: hidden;
 
         & .kbq-select__match-hidden-text {
-            flex: 0 0 40px;
+            // This is the box the matcher reserves for the "+N" counter, and `flex-basis` obeys
+            // `box-sizing` exactly as `width` does. Under a global `border-box` reset in a consuming
+            // application the padding would come out of the reserved width, so the counter would get
+            // 8px less room than `KbqSelect` measured for it and the tag count would be off by one
+            // at the boundary.
+            box-sizing: content-box;
+
+            flex: 0 0 var(--kbq-form-field-size-addon-width);
             align-self: center;
-            padding-left: 4px;
+            padding-left: var(--kbq-size-xxs);
             padding-right: var(--kbq-select-size-multiple-content-gap, var(--kbq-size-xxs));
 
             text-align: right;
@@ -167,6 +174,11 @@
 %kbq-select-panel {
     min-width: 100%; // prevents some animation twitching and test inconsistencies in IE11
 
+    // Caps how far the panel grows with its content. `min-width` above intentionally wins over this,
+    // so the panel is never narrower than its trigger and an explicit `panelWidth` is never clamped.
+    // The token is deliberately left undeclared so that a `:root` override reaches every panel.
+    max-width: var(--kbq-panel-size-width-max, 640px);
+
     overflow: hidden;
 
     border-radius: var(--kbq-select-panel-size-border-radius, var(--kbq-size-border-radius));
@@ -212,6 +224,11 @@
 }
 
 %kbq-select-content {
+    // Content-box so that the cap counts whole options and is not eaten by the padding below — and so
+    // that a global `border-box` reset in a consuming app cannot change what `panelMaxHeight` means.
+    // The token is deliberately left undeclared so that a `:root` override reaches every panel.
+    box-sizing: initial;
+
     max-height: var(--kbq-select-panel-size-max-height, 256px);
     padding: var(--kbq-size-xxs);
     overflow: hidden auto;

package/core/styles/common/_tokens.scss

@@ -1,14 +1,5 @@
-@use 'sass:map';
 @use 'sass:meta';
 
-@use '../tokens';
-
-$tokens: meta.module-variables(tokens) !default;
-
-@function getToken($name) {
-    @return map.get($tokens, $name);
-}
-
 @mixin kbq-css-font-variable($component, $component-property, $font-property, $font) {
     #{$font-property}: var(--kbq-#{$component}-#{$font}#{$component-property}-#{$font-property});
 }

package/core/styles/theming/_index.scss

@@ -1,2 +1 @@
-@forward 'components-theming';
 @forward 'theming';

package/core/styles/theming/_theming.scss

@@ -1,12 +1,12 @@
 @use 'sass:map';
 @use 'sass:meta';
 
-@use 'components-theming' as *;
-
+// @deprecated Unused internally. Will be removed in the next major version.
 @function kbq-contrast($palette, $hue) {
     @return map.get(map.get($palette, contrast), $hue);
 }
 
+// @deprecated @TODO: unused. Will be removed in the next major version.
 @function kbq-palette($base-palette, $default) {
     $result: map.merge(
         $base-palette,
@@ -28,6 +28,7 @@
     @return $result;
 }
 
+// @deprecated @TODO: unused. Will be removed in the next major version.
 @function kbq-color($palette, $hue: default, $opacity: null) {
     // If hueKey is a number between zero and one, then it actually contains an
     // opacity value, so recall this function with the default hue and that given opacity.
@@ -42,14 +43,34 @@
 }
 
 // Mixin that renders all of the core styles that depend on the theme.
-
+// @TODO: Argument is unused. will be removed in next major release
 @mixin kbq-core-theme($theme: null) {
     .kbq-app-background {
         background: var(--kbq-background-bg);
         color: var(--kbq-foreground-contrast);
     }
+
+    // Which palette the browser paints *its own* surfaces with — scrollbars, native controls, the
+    // autofill highlight, spellcheck. A theme is a class, and a class tells the browser nothing, so
+    // without this every one of those renders from the light palette however dark the application
+    // looks. Autofill is where it shows most: refocusing a filled field reopens the browser's own
+    // popup, and in that state it paints the highlight and the text itself, over author styles that
+    // normally hide it — a light block with black text in the middle of a dark form.
+
+    // Both declarations at the same specificity on purpose. `color-scheme` inherits, so the nearest
+    // ancestor carrying either class decides, and a light subtree inside a dark application gets the
+    // light palette. Weighting one over the other — or scoping this to a component — inverts exactly
+    // that case.
+    .kbq-light {
+        color-scheme: light;
+    }
+
+    .kbq-dark {
+        color-scheme: dark;
+    }
 }
 
+// @deprecated @TODO: unused. Will be removed in next major release
 @function _theme_foreground($tokens, $scheme) {
     @return (
         white: map.get($tokens, '#{$scheme}-foreground-white'),
@@ -75,6 +96,7 @@
     );
 }
 
+// @deprecated @TODO: unused. Will be removed in next major release
 @function _theme_background($tokens, $scheme) {
     @return (
         bg: map.get($tokens, '#{$scheme}-background-bg'),
@@ -99,6 +121,7 @@
     );
 }
 
+// @deprecated @TODO: unused. Will be removed in next major release
 @function _theme_icon($tokens, $scheme) {
     @return (
         on-contrast: map.get($tokens, '#{$scheme}-icon-on-contrast'),
@@ -114,6 +137,7 @@
     );
 }
 
+// @deprecated @TODO: unused. Will be removed in next major release
 @function _theme_line($tokens, $scheme) {
     @return (
         theme: map.get($tokens, '#{$scheme}-line-theme'),
@@ -131,6 +155,7 @@
     );
 }
 
+// @deprecated @TODO: unused. Will be removed in next major release
 @function _theme_states-background($tokens, $scheme) {
     @return (
         disabled: map.get($tokens, '#{$scheme}-states-background-disabled'),
@@ -151,6 +176,7 @@
     );
 }
 
+// @deprecated @TODO: unused. Will be removed in next major release
 @function _theme_states-foreground($tokens, $scheme) {
     @return (
         disabled: map.get($tokens, '#{$scheme}-states-foreground-disabled'),
@@ -161,6 +187,7 @@
     );
 }
 
+// @deprecated @TODO: unused. Will be removed in next major release
 @function _theme_states-icon($tokens, $scheme) {
     @return (
         theme-hover: map.get($tokens, '#{$scheme}-states-icon-theme-hover'),
@@ -181,6 +208,7 @@
     );
 }
 
+// @deprecated @TODO: unused. Will be removed in next major release
 @function _theme_states-line($tokens, $scheme) {
     @return (
         focus: map.get($tokens, '#{$scheme}-states-line-focus'),
@@ -190,6 +218,7 @@
     );
 }
 
+// @deprecated @TODO: unused. Will be removed in next major release
 @function _theme_states($tokens, $scheme) {
     @return (
         background: _theme_states-background($tokens, $scheme),
@@ -201,6 +230,7 @@
     );
 }
 
+// @deprecated @TODO: unused. Will be removed in next major release
 @function kbq-palette($base-palette, $default) {
     @return map.merge(
         $base-palette,
@@ -210,6 +240,7 @@
     );
 }
 
+// @deprecated @TODO: unused. Will be removed in next major release
 @function _theme_palette($tokens, $scheme, $name) {
     @return kbq-palette(
         map.get($tokens, '#{$scheme}-#{$name}-palette'),
@@ -236,7 +267,6 @@
         white: _theme_palette($tokens, $scheme, white),
         black: _theme_palette($tokens, $scheme, black),
         purple: _theme_palette($tokens, $scheme, purple),
-        components: kbq-components-theme($tokens, $scheme),
         tokens: $tokens
     );
 }
@@ -260,7 +290,6 @@
         white: _theme_palette($tokens, $scheme, white),
         black: _theme_palette($tokens, $scheme, black),
         purple: _theme_palette($tokens, $scheme, purple),
-        components: kbq-components-theme($tokens, $scheme),
         tokens: $tokens
     );
 }

package/datepicker/index.d.ts

@@ -1,15 +1,15 @@
 import * as _angular_core from '@angular/core';
-import { OnChanges, SimpleChanges, AfterContentInit, OnDestroy, AfterViewInit, InjectionToken, DoCheck, ElementRef, EventEmitter } from '@angular/core';
-import { Subject } from 'rxjs';
+import { OnChanges, SimpleChanges, AfterContentInit, OnDestroy, InjectionToken, AfterViewInit, DoCheck, ElementRef, EventEmitter } from '@angular/core';
+import { Subject, Observable } from 'rxjs';
 import * as _koobiq_components_core from '@koobiq/components/core';
-import { DateAdapter, ErrorStateMatcher } from '@koobiq/components/core';
+import { DateAdapter, ErrorStateMatcher, KbqSiblingPopup } from '@koobiq/components/core';
 import { AnimationTriggerMetadata } from '@angular/animations';
+import * as _koobiq_components_form_field from '@koobiq/components/form-field';
+import { KbqFormFieldControl } from '@koobiq/components/form-field';
 import { ControlValueAccessor, Validator, AbstractControl, ValidationErrors } from '@angular/forms';
-import * as i15 from '@koobiq/components/form-field';
-import { KbqFormFieldControl, KbqFormField } from '@koobiq/components/form-field';
 import { KbqTooltipTrigger } from '@koobiq/components/tooltip';
 import * as i2 from '@angular/cdk/overlay';
-import { OverlayRef, ScrollStrategy, Overlay } from '@angular/cdk/overlay';
+import { ScrollStrategy, Overlay, OverlayRef } from '@angular/cdk/overlay';
 import * as i1 from '@koobiq/components/button';
 import * as i3 from '@angular/cdk/a11y';
 import * as i4 from '@angular/cdk/portal';
@@ -126,6 +126,7 @@ declare class KbqCalendarHeader<D> implements AfterContentInit {
  */
 declare class KbqMonthView<D> implements AfterContentInit {
     private changeDetectorRef;
+    private readonly timezoneService;
     adapter: DateAdapter<D>;
     /**
      * The date to display in this month view (everything other than the month and year is ignored).
@@ -282,7 +283,10 @@ declare const kbqDatepickerAnimations: {
     readonly fadeInCalendar: AnimationTriggerMetadata;
 };
 
-/** Injection token that determines the scroll handling while the calendar is open. */
+/**
+ * Injection token that determines the scroll handling while the calendar is open. The root default keeps the
+ * datepicker usable outside `KbqDatepickerModule`'s injector; providing the token anywhere still wins over it.
+ */
 declare const KBQ_DATEPICKER_SCROLL_STRATEGY: InjectionToken<() => ScrollStrategy>;
 /** @docs-private */
 declare function KBQ_DATEPICKER_SCROLL_STRATEGY_FACTORY(overlay: Overlay): () => ScrollStrategy;
@@ -458,9 +462,10 @@ declare class KbqDatepickerInput<D> implements KbqFormFieldControl<D>, ControlVa
     elementRef: ElementRef<HTMLInputElement>;
     private readonly renderer;
     readonly adapter: DateAdapter<D>;
+    private readonly timezoneService;
     private readonly dateFormats;
     /** @docs-private */
-    protected readonly formField: KbqFormField | null;
+    protected readonly formField: _koobiq_components_form_field.KbqFormField | null;
     /** @docs-private */
     protected readonly localeService: _koobiq_components_core.KbqLocaleService | null;
     /** @docs-private */
@@ -495,11 +500,27 @@ declare class KbqDatepickerInput<D> implements KbqFormFieldControl<D>, ControlVa
     get value(): D | null;
     set value(value: D | null);
     private _value;
-    /** The minimum valid date. */
+    /**
+     * The minimum valid date. Drives validation only — including dates typed or pasted into the
+     * input — and reports `kbqDatepickerMin`. The calendar is restricted separately, by `minDate`
+     * on the associated `<kbq-datepicker>`.
+     *
+     * Compared down to the millisecond, not by calendar day: the input keeps the time part of the
+     * value it parses, and the comparison is made on wall-clock components rather than on absolute
+     * time.
+     */
     get min(): D | null;
     set min(value: D | null);
     private _min;
-    /** The maximum valid date. */
+    /**
+     * The maximum valid date. Drives validation only — including dates typed or pasted into the
+     * input — and reports `kbqDatepickerMax`. The calendar is restricted separately, by `maxDate`
+     * on the associated `<kbq-datepicker>`.
+     *
+     * Compared down to the millisecond, not by calendar day: the input keeps the time part of the
+     * value it parses, so an upper bound meant to include its whole day has to be the end of that
+     * day.
+     */
     get max(): D | null;
     set max(value: D | null);
     private _max;
@@ -525,9 +546,7 @@ declare class KbqDatepickerInput<D> implements KbqFormFieldControl<D>, ControlVa
     set errorState(value: boolean);
     private get readyForParse();
     private get selectionStart();
-    private set selectionStart(value);
     private get selectionEnd();
-    private set selectionEnd(value);
     private control;
     private readonly uid;
     private datepickerSubscription;
@@ -581,6 +600,7 @@ declare class KbqDatepickerInput<D> implements KbqFormFieldControl<D>, ControlVa
     private spaceKeyHandler;
     private getNewValue;
     private setViewValue;
+    private setSelection;
     private replaceSymbols;
     private getDateFromString;
     private getDefaultValue;
@@ -628,7 +648,7 @@ declare class KbqDatepickerInput<D> implements KbqFormFieldControl<D>, ControlVa
     private getDigitPositions;
     private createDate;
     private createDateTime;
-    private correctCursorPosition;
+    private correctedCursorPosition;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<KbqDatepickerInput<any>, never>;
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<KbqDatepickerInput<any>, "input[kbqDatepicker], input[kbqCalendar]", ["kbqDatepickerInput"], { "errorStateMatcher": { "alias": "errorStateMatcher"; "required": false; }; "placeholder": { "alias": "placeholder"; "required": false; }; "required": { "alias": "required"; "required": false; }; "kbqDatepicker": { "alias": "kbqDatepicker"; "required": false; }; "kbqCalendar": { "alias": "kbqCalendar"; "required": false; }; "kbqDatepickerFilter": { "alias": "kbqDatepickerFilter"; "required": false; }; "value": { "alias": "value"; "required": false; }; "min": { "alias": "min"; "required": false; }; "max": { "alias": "max"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "id": { "alias": "id"; "required": false; }; "kbqValidationTooltip": { "alias": "kbqValidationTooltip"; "required": false; }; }, { "incorrectInput": "incorrectInput"; "dateChange": "dateChange"; "dateInput": "dateInput"; }, never, never, true, never>;
 }
@@ -669,13 +689,24 @@ declare class KbqDatepickerToggleIcon {
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<KbqDatepickerToggleIcon, never>;
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<KbqDatepickerToggleIcon, "[kbqDatepickerToggleIcon]", never, {}, {}, never, never, true, never>;
 }
-declare class KbqDatepickerToggleIconComponent<D> implements AfterContentInit, OnChanges, OnDestroy {
+declare class KbqDatepickerToggleIconComponent<D> implements AfterContentInit, OnChanges, OnDestroy, KbqSiblingPopup {
     /** Whether the toggle button is disabled. */
     get disabled(): boolean;
     set disabled(value: boolean);
     private _disabled;
     /** Datepicker instance that the button will toggle. */
     readonly datepicker: _angular_core.InputSignal<KbqDatepicker<D>>;
+    /** Whether the calendar is currently on screen. Part of the `KbqSiblingPopup` contract. */
+    get isAttached(): boolean;
+    /**
+     * Emits `true` when the calendar opens and `false` when it closes. Part of the `KbqSiblingPopup`
+     * contract.
+     *
+     * Built on top of the `datepicker` signal rather than read once, because the instance is bound after the
+     * consumers of this stream (a tooltip on the same element subscribes in its constructor) and may be
+     * swapped later — the same reason `watchStateChanges` is re-run from `ngOnChanges`.
+     */
+    readonly openedChange: Observable<boolean>;
     private readonly destroyRef;
     private readonly cdr;
     private stateChangesSubscription;
@@ -691,7 +722,7 @@ declare class KbqDatepickerToggleIconComponent<D> implements AfterContentInit, O
 
 declare class KbqDatepickerModule {
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<KbqDatepickerModule, never>;
-    static ɵmod: _angular_core.ɵɵNgModuleDeclaration<KbqDatepickerModule, never, [typeof i1.KbqButtonModule, typeof i2.OverlayModule, typeof i3.A11yModule, typeof i4.PortalModule, typeof i5.KbqSelectModule, typeof i6.KbqIconModule, typeof KbqDatepickerToggleIconComponent, typeof i8.TitleCasePipe, typeof KbqCalendar, typeof KbqCalendarBody, typeof KbqDatepicker, typeof KbqDatepickerContent, typeof KbqDatepickerInput, typeof KbqDatepickerToggleIcon, typeof KbqMonthView, typeof KbqCalendarHeader], [typeof KbqCalendar, typeof KbqCalendarBody, typeof KbqDatepicker, typeof KbqDatepickerContent, typeof KbqDatepickerInput, typeof KbqDatepickerToggleIcon, typeof KbqDatepickerToggleIconComponent, typeof KbqMonthView, typeof KbqCalendarHeader, typeof i15.KbqFormFieldModule]>;
+    static ɵmod: _angular_core.ɵɵNgModuleDeclaration<KbqDatepickerModule, never, [typeof i1.KbqButtonModule, typeof i2.OverlayModule, typeof i3.A11yModule, typeof i4.PortalModule, typeof i5.KbqSelectModule, typeof i6.KbqIconModule, typeof KbqDatepickerToggleIconComponent, typeof i8.TitleCasePipe, typeof KbqCalendar, typeof KbqCalendarBody, typeof KbqDatepicker, typeof KbqDatepickerContent, typeof KbqDatepickerInput, typeof KbqDatepickerToggleIcon, typeof KbqMonthView, typeof KbqCalendarHeader], [typeof KbqCalendar, typeof KbqCalendarBody, typeof KbqDatepicker, typeof KbqDatepickerContent, typeof KbqDatepickerInput, typeof KbqDatepickerToggleIcon, typeof KbqDatepickerToggleIconComponent, typeof KbqMonthView, typeof KbqCalendarHeader, typeof _koobiq_components_form_field.KbqFormFieldModule]>;
     static ɵinj: _angular_core.ɵɵInjectorDeclaration<KbqDatepickerModule>;
 }
 

package/dl/dl.scss

@@ -7,6 +7,32 @@
 
     grid-template-columns: repeat(4, 1fr);
 
+    &.kbq-dl_vertical-align-center {
+        align-items: center;
+    }
+
+    &.kbq-dl_vertical-align-end {
+        align-items: end;
+    }
+
+    &.kbq-dl_horizontal-align-center {
+        justify-items: center;
+    }
+
+    &.kbq-dl_horizontal-align-end {
+        justify-items: end;
+    }
+
+    // Let the columns keep their `1fr` ratio instead of being stretched by an unbreakable string: `min-width: 0`
+    // drops the grid item's content-based automatic minimum, and `break-word` breaks such a string only when it
+    // does not fit. `anywhere` is deliberately avoided — it would also shrink the min-content size to a single
+    // character and leak that to any ancestor that sizes itself to content.
+    .kbq-dt,
+    .kbq-dd {
+        min-width: 0;
+        overflow-wrap: break-word;
+    }
+
     .kbq-dt {
         grid-column: 1;
     }

package/dl/index.d.ts

@@ -4,9 +4,15 @@ import { Subject } from 'rxjs';
 import * as i1 from '@angular/cdk/a11y';
 import * as i2 from '@angular/cdk/platform';
 
+/** Supported alignment values for description list items. */
+type KbqDlAlign = 'start' | 'center' | 'end';
 declare class KbqDlComponent implements AfterContentInit, OnDestroy {
     readonly minWidth: i0.InputSignal<number>;
     readonly wide: i0.InputSignal<boolean>;
+    /** Vertical alignment of `kbq-dt` and `kbq-dd` items. */
+    readonly verticalAlign: i0.InputSignal<KbqDlAlign>;
+    /** Horizontal alignment of `kbq-dt` and `kbq-dd` items. */
+    readonly horizontalAlign: i0.InputSignal<KbqDlAlign>;
     vertical: boolean | null;
     readonly resizeStream: Subject<Event>;
     private readonly resizeDebounceInterval;
@@ -18,7 +24,7 @@ declare class KbqDlComponent implements AfterContentInit, OnDestroy {
     ngOnDestroy(): void;
     private readonly updateState;
     static ɵfac: i0.ɵɵFactoryDeclaration<KbqDlComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<KbqDlComponent, "kbq-dl", never, { "minWidth": { "alias": "minWidth"; "required": false; "isSignal": true; }; "wide": { "alias": "wide"; "required": false; "isSignal": true; }; "vertical": { "alias": "vertical"; "required": false; }; }, {}, never, ["*"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<KbqDlComponent, "kbq-dl", never, { "minWidth": { "alias": "minWidth"; "required": false; "isSignal": true; }; "wide": { "alias": "wide"; "required": false; "isSignal": true; }; "verticalAlign": { "alias": "verticalAlign"; "required": false; "isSignal": true; }; "horizontalAlign": { "alias": "horizontalAlign"; "required": false; "isSignal": true; }; "vertical": { "alias": "vertical"; "required": false; }; }, {}, never, ["*"], true, never>;
 }
 declare class KbqDtComponent {
     static ɵfac: i0.ɵɵFactoryDeclaration<KbqDtComponent, never>;
@@ -36,3 +42,4 @@ declare class KbqDlModule {
 }
 
 export { KbqDdComponent, KbqDlComponent, KbqDlModule, KbqDtComponent };
+export type { KbqDlAlign };