@neuravision/ng-construct 0.4.2 → 0.5.0

package/fesm2022/neuravision-ng-construct.mjs

@@ -1,9 +1,18 @@
 import * as i0 from '@angular/core';
-import { input, output, signal, computed, ChangeDetectionStrategy, Component, inject, forwardRef, model, booleanAttribute, viewChild, contentChildren, effect, DOCUMENT, contentChild, ElementRef, TemplateRef, Directive, Injectable, viewChildren, Renderer2, InjectionToken, numberAttribute, Pipe } from '@angular/core';
-import { NG_VALUE_ACCESSOR } from '@angular/forms';
-import { NgTemplateOutlet } from '@angular/common';
+import { InjectionToken, inject, input, output, signal, computed, ChangeDetectionStrategy, Component, Injectable, forwardRef, model, booleanAttribute, viewChild, contentChildren, effect, DOCUMENT as DOCUMENT$1, isDevMode, contentChild, ElementRef, TemplateRef, Directive, viewChildren, Renderer2, numberAttribute, Pipe } from '@angular/core';
+import { DOCUMENT, NgTemplateOutlet } from '@angular/common';
+import { NG_VALUE_ACCESSOR, NG_VALIDATORS } from '@angular/forms';
 import { RouterLink, RouterLinkActive } from '@angular/router';
 
+/**
+ * Injection token to provide custom i18n strings for {@link AfAlertComponent}.
+ *
+ * @example
+ * providers: [{ provide: AF_ALERT_I18N, useValue: { dismiss: 'Schliessen', dismissed: 'Warnung geschlossen' } }]
+ */
+const AF_ALERT_I18N = new InjectionToken('AF_ALERT_I18N', {
+    factory: () => ({ dismiss: 'Dismiss alert', dismissed: 'Alert dismissed' }),
+});
 /**
  * Alert component for displaying contextual feedback messages.
  *
@@ -11,6 +20,14 @@ import { RouterLink, RouterLinkActive } from '@angular/router';
  * - `danger` / `warning` → `role="alert"` (assertive announcement)
  * - `info` / `success` → `role="status"` (polite announcement)
  *
+ * ### Accessibility
+ * - The dismiss button is keyboard-accessible via Tab, activated by Enter/Space (native `<button>`)
+ * - When dismissed, a screen-reader announcement is made via an `aria-live="polite"` region
+ * - The icon slot is marked `aria-hidden="true"` to prevent redundant announcements
+ * - The `aria-label` on the dismiss button is configurable via {@link AF_ALERT_I18N} for i18n
+ * - Supports `forced-colors` (Windows High Contrast) mode
+ * - Uses CSS logical properties for RTL layout support
+ *
  * @example
  * <af-alert variant="warning" [dismissible]="true" (dismissed)="onDismiss()">
  *   <span icon>⚠</span>
@@ -22,14 +39,17 @@ import { RouterLink, RouterLinkActive } from '@angular/router';
  * </af-alert>
  */
 class AfAlertComponent {
-    /** Color variant determining the alert's visual style and ARIA role */
+    i18n = inject(AF_ALERT_I18N);
+    /** Color variant determining the alert's visual style and ARIA role. */
     variant = input('info', ...(ngDevMode ? [{ debugName: "variant" }] : []));
-    /** Whether the alert can be dismissed by the user */
+    /** Whether the alert can be dismissed by the user. */
     dismissible = input(false, ...(ngDevMode ? [{ debugName: "dismissible" }] : []));
-    /** Emits when the user dismisses the alert */
+    /** Emits when the user dismisses the alert. */
     dismissed = output();
-    /** Controls alert visibility */
+    /** Controls alert visibility. */
     visible = signal(true, ...(ngDevMode ? [{ debugName: "visible" }] : []));
+    /** @internal Screen-reader announcement text. */
+    liveAnnouncement = signal('', ...(ngDevMode ? [{ debugName: "liveAnnouncement" }] : []));
     alertClasses = computed(() => {
         const classes = ['ct-alert'];
         if (this.dismissible()) {
@@ -46,10 +66,12 @@ class AfAlertComponent {
         const v = this.variant();
         return v === 'danger' || v === 'warning' ? 'alert' : 'status';
     }, ...(ngDevMode ? [{ debugName: "alertRole" }] : []));
-    /** Hides the alert and emits the dismissed event */
+    /** Hides the alert and emits the dismissed event. */
     dismiss() {
         this.visible.set(false);
         this.dismissed.emit();
+        this.liveAnnouncement.set('');
+        setTimeout(() => this.liveAnnouncement.set(this.i18n.dismissed));
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.2", ngImport: i0, type: AfAlertComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.1.2", type: AfAlertComponent, isStandalone: true, selector: "af-alert", inputs: { variant: { classPropertyName: "variant", publicName: "variant", isSignal: true, isRequired: false, transformFunction: null }, dismissible: { classPropertyName: "dismissible", publicName: "dismissible", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { dismissed: "dismissed" }, ngImport: i0, template: `
@@ -76,14 +98,17 @@ class AfAlertComponent {
           <button
             type="button"
             class="af-alert__dismiss"
-            aria-label="Dismiss alert"
+            [attr.aria-label]="i18n.dismiss"
             (click)="dismiss()">
             <span class="ct-icon ct-icon--sm" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg></span>
           </button>
         }
       </div>
     }
-  `, isInline: true, styles: [":host{display:contents}.ct-alert--dismissible{position:relative;padding-right:2.5rem}.af-alert__dismiss{position:absolute;top:.625rem;right:.625rem;display:inline-flex;align-items:center;justify-content:center;width:1.5rem;height:1.5rem;padding:0;border:none;background:none;border-radius:var(--radius-sm, .25rem);color:var(--color-text-secondary);font-size:1.25rem;line-height:1;cursor:pointer}.af-alert__dismiss:hover{color:var(--color-text-primary)}.af-alert__dismiss:focus-visible{outline:2px solid var(--ct-alert-accent, var(--color-brand-primary));outline-offset:2px}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+    <span class="af-alert__sr-only" aria-live="polite" aria-atomic="true">
+      {{ liveAnnouncement() }}
+    </span>
+  `, isInline: true, styles: [":host{display:contents}.ct-alert--dismissible{position:relative;padding-inline-end:2.5rem}.af-alert__dismiss{position:absolute;inset-block-start:.625rem;inset-inline-end:.625rem;display:inline-flex;align-items:center;justify-content:center;width:1.5rem;height:1.5rem;min-width:24px;min-height:24px;padding:0;border:none;background:none;border-radius:var(--radius-sm, .25rem);color:var(--color-text-secondary);font-size:1.25rem;line-height:1;cursor:pointer}.af-alert__dismiss:hover{color:var(--color-text-primary)}.af-alert__dismiss:focus-visible{outline:2px solid var(--ct-alert-accent, var(--color-brand-primary));outline-offset:2px}@media(forced-colors:active){.af-alert__dismiss{border:1px solid ButtonText}.af-alert__dismiss:focus-visible{outline-color:Highlight}}.af-alert__sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImport: i0, type: AfAlertComponent, decorators: [{
             type: Component,
@@ -111,16 +136,183 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImpor
           <button
             type="button"
             class="af-alert__dismiss"
-            aria-label="Dismiss alert"
+            [attr.aria-label]="i18n.dismiss"
             (click)="dismiss()">
             <span class="ct-icon ct-icon--sm" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg></span>
           </button>
         }
       </div>
     }
-  `, styles: [":host{display:contents}.ct-alert--dismissible{position:relative;padding-right:2.5rem}.af-alert__dismiss{position:absolute;top:.625rem;right:.625rem;display:inline-flex;align-items:center;justify-content:center;width:1.5rem;height:1.5rem;padding:0;border:none;background:none;border-radius:var(--radius-sm, .25rem);color:var(--color-text-secondary);font-size:1.25rem;line-height:1;cursor:pointer}.af-alert__dismiss:hover{color:var(--color-text-primary)}.af-alert__dismiss:focus-visible{outline:2px solid var(--ct-alert-accent, var(--color-brand-primary));outline-offset:2px}\n"] }]
+    <span class="af-alert__sr-only" aria-live="polite" aria-atomic="true">
+      {{ liveAnnouncement() }}
+    </span>
+  `, styles: [":host{display:contents}.ct-alert--dismissible{position:relative;padding-inline-end:2.5rem}.af-alert__dismiss{position:absolute;inset-block-start:.625rem;inset-inline-end:.625rem;display:inline-flex;align-items:center;justify-content:center;width:1.5rem;height:1.5rem;min-width:24px;min-height:24px;padding:0;border:none;background:none;border-radius:var(--radius-sm, .25rem);color:var(--color-text-secondary);font-size:1.25rem;line-height:1;cursor:pointer}.af-alert__dismiss:hover{color:var(--color-text-primary)}.af-alert__dismiss:focus-visible{outline:2px solid var(--ct-alert-accent, var(--color-brand-primary));outline-offset:2px}@media(forced-colors:active){.af-alert__dismiss{border:1px solid ButtonText}.af-alert__dismiss:focus-visible{outline-color:Highlight}}.af-alert__sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}\n"] }]
         }], propDecorators: { variant: [{ type: i0.Input, args: [{ isSignal: true, alias: "variant", required: false }] }], dismissible: [{ type: i0.Input, args: [{ isSignal: true, alias: "dismissible", required: false }] }], dismissed: [{ type: i0.Output, args: ["dismissed"] }] } });
 
+/**
+ * Test harness for AfAlertComponent.
+ *
+ * Provides a semantic API for interacting with the alert in tests,
+ * abstracting DOM details behind readable method names.
+ *
+ * @example
+ * const harness = new AfAlertHarness(fixture.nativeElement);
+ * expect(harness.getVariant()).toBe('info');
+ * expect(harness.getRole()).toBe('status');
+ * harness.dismiss();
+ */
+class AfAlertHarness {
+    hostEl;
+    constructor(container) {
+        const el = container.querySelector('af-alert');
+        if (!el) {
+            throw new Error('AfAlertHarness: af-alert element not found in container.');
+        }
+        this.hostEl = el;
+    }
+    /** Returns the inner `.ct-alert` wrapper element, or `null` if the alert is not visible. */
+    getAlertElement() {
+        return this.hostEl.querySelector('.ct-alert');
+    }
+    /** Returns the `data-variant` attribute value. Throws if the alert is not visible. */
+    getVariant() {
+        const el = this.requireVisible();
+        return el.getAttribute('data-variant') ?? '';
+    }
+    /** Returns the ARIA `role` attribute value. Throws if the alert is not visible. */
+    getRole() {
+        const el = this.requireVisible();
+        return el.getAttribute('role') ?? '';
+    }
+    /** Returns the full trimmed text content of the alert. Throws if not visible. */
+    getText() {
+        const el = this.requireVisible();
+        return el.textContent?.trim() ?? '';
+    }
+    /** Returns the trimmed text content of the title slot. Throws if not visible. */
+    getTitle() {
+        const el = this.requireVisible();
+        const title = el.querySelector('.ct-alert__title');
+        return title?.textContent?.trim() ?? '';
+    }
+    /** Returns whether the alert is currently visible in the DOM. */
+    isVisible() {
+        return this.getAlertElement() !== null;
+    }
+    /** Returns whether the alert has a dismiss button. Throws if not visible. */
+    isDismissible() {
+        const el = this.requireVisible();
+        return el.querySelector('.af-alert__dismiss') !== null;
+    }
+    /** Clicks the dismiss button. Throws if the alert is not visible or not dismissible. */
+    dismiss() {
+        const btn = this.getDismissButton();
+        if (!btn) {
+            throw new Error('AfAlertHarness: dismiss button not found. Is the alert dismissible?');
+        }
+        btn.click();
+    }
+    /** Returns the dismiss button element, or `null` if not present. */
+    getDismissButton() {
+        return (this.getAlertElement()?.querySelector('.af-alert__dismiss') ?? null);
+    }
+    /** Returns the `aria-live` region element for screen-reader announcements. */
+    getLiveRegion() {
+        return this.hostEl.querySelector('[aria-live="polite"]');
+    }
+    requireVisible() {
+        const el = this.getAlertElement();
+        if (!el) {
+            throw new Error('AfAlertHarness: alert is not visible.');
+        }
+        return el;
+    }
+}
+
+/**
+ * Lightweight service that announces messages to screen readers
+ * via an `aria-live` region. No `@angular/cdk` dependency required.
+ *
+ * @example
+ * private announcer = inject(AriaLiveAnnouncer);
+ * this.announcer.announce('Section expanded');
+ */
+class AriaLiveAnnouncer {
+    document = inject(DOCUMENT);
+    liveEl = null;
+    clearTimer = null;
+    /** Announce a message to screen readers. */
+    announce(message, politeness = 'polite') {
+        const el = this.getOrCreateLiveElement();
+        el.setAttribute('aria-live', politeness);
+        // Clear then re-set so assistive tech registers the change.
+        el.textContent = '';
+        if (this.clearTimer) {
+            clearTimeout(this.clearTimer);
+        }
+        // Small delay so the DOM mutation is picked up as a new announcement.
+        setTimeout(() => {
+            el.textContent = message;
+        }, 50);
+        // Auto-clear after 3 seconds to avoid stale text.
+        this.clearTimer = setTimeout(() => {
+            el.textContent = '';
+        }, 3000);
+    }
+    ngOnDestroy() {
+        if (this.clearTimer) {
+            clearTimeout(this.clearTimer);
+        }
+        this.liveEl?.remove();
+        this.liveEl = null;
+    }
+    getOrCreateLiveElement() {
+        if (this.liveEl)
+            return this.liveEl;
+        const el = this.document.createElement('div');
+        el.setAttribute('aria-live', 'polite');
+        el.setAttribute('aria-atomic', 'true');
+        el.classList.add('cdk-visually-hidden');
+        // Visually hidden but accessible to screen readers.
+        Object.assign(el.style, {
+            position: 'absolute',
+            width: '1px',
+            height: '1px',
+            padding: '0',
+            margin: '-1px',
+            overflow: 'hidden',
+            clip: 'rect(0, 0, 0, 0)',
+            whiteSpace: 'nowrap',
+            border: '0',
+        });
+        this.document.body.appendChild(el);
+        this.liveEl = el;
+        return el;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.2", ngImport: i0, type: AriaLiveAnnouncer, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.1.2", ngImport: i0, type: AriaLiveAnnouncer, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImport: i0, type: AriaLiveAnnouncer, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
+/**
+ * Injection token to override accordion screen-reader announcements.
+ *
+ * @example
+ * providers: [{
+ *   provide: AF_ACCORDION_I18N,
+ *   useValue: { expanded: '{heading} ausgeklappt', collapsed: '{heading} eingeklappt' },
+ * }]
+ */
+const AF_ACCORDION_I18N = new InjectionToken('AfAccordionI18n', {
+    factory: () => ({
+        expanded: '{heading} expanded',
+        collapsed: '{heading} collapsed',
+    }),
+});
+
 let nextId$1 = 0;
 /**
  * Individual accordion item used within af-accordion.
@@ -133,6 +325,8 @@ let nextId$1 = 0;
 class AfAccordionItemComponent {
     itemId = nextId$1++;
     accordion = inject(forwardRef(() => AfAccordionComponent), { optional: true });
+    announcer = inject(AriaLiveAnnouncer);
+    i18n = inject(AF_ACCORDION_I18N);
     /** Heading text displayed in the accordion trigger. */
     heading = input.required(...(ngDevMode ? [{ debugName: "heading" }] : []));
     /** Whether this item is expanded (supports two-way binding). */
@@ -165,6 +359,8 @@ class AfAccordionItemComponent {
         if (willExpand) {
             this.accordion?.onItemExpanded(this);
         }
+        const template = willExpand ? this.i18n.expanded : this.i18n.collapsed;
+        this.announcer.announce(template.replace('{heading}', this.heading()));
     }
     /** Programmatically collapse this item. */
     collapse() {
@@ -354,6 +550,96 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImpor
   `, styles: [":host{display:block}\n"] }]
         }], propDecorators: { multi: [{ type: i0.Input, args: [{ isSignal: true, alias: "multi", required: false }] }], bordered: [{ type: i0.Input, args: [{ isSignal: true, alias: "bordered", required: false }] }], items: [{ type: i0.ContentChildren, args: [i0.forwardRef(() => AfAccordionItemComponent), { isSignal: true }] }] } });
 
+/**
+ * Test harness for AfAccordionItemComponent.
+ *
+ * Provides a semantic API for interacting with a single accordion item,
+ * abstracting DOM details behind readable method names.
+ */
+class AfAccordionItemHarness {
+    hostEl;
+    constructor(hostEl) {
+        this.hostEl = hostEl;
+    }
+    /** Returns the heading text. */
+    getHeading() {
+        const heading = this.hostEl.querySelector('.ct-accordion__heading');
+        return heading?.textContent?.trim() ?? '';
+    }
+    /** Returns whether the item is expanded. */
+    isExpanded() {
+        return this.getTriggerElement().getAttribute('aria-expanded') === 'true';
+    }
+    /** Returns whether the item is disabled. */
+    isDisabled() {
+        return this.getTriggerElement().getAttribute('aria-disabled') === 'true';
+    }
+    /** Clicks the trigger to toggle the item. */
+    toggle() {
+        this.getTriggerElement().click();
+    }
+    /** Returns the trigger (summary) element. */
+    getTriggerElement() {
+        const summary = this.hostEl.querySelector('summary');
+        if (!summary) {
+            throw new Error('AfAccordionItemHarness: <summary> element not found.');
+        }
+        return summary;
+    }
+    /** Returns the content panel element. */
+    getContentElement() {
+        const panel = this.hostEl.querySelector('[role="region"]');
+        if (!panel) {
+            throw new Error('AfAccordionItemHarness: content region not found.');
+        }
+        return panel;
+    }
+    /** Returns the `aria-controls` value of the trigger. */
+    getAriaControls() {
+        return this.getTriggerElement().getAttribute('aria-controls');
+    }
+    /** Returns the `aria-expanded` value of the trigger. */
+    getAriaExpanded() {
+        return this.getTriggerElement().getAttribute('aria-expanded');
+    }
+}
+/**
+ * Test harness for AfAccordionComponent.
+ *
+ * @example
+ * const harness = new AfAccordionHarness(fixture.nativeElement);
+ * expect(harness.getItems()).toHaveLength(3);
+ * harness.getItem(0).toggle();
+ */
+class AfAccordionHarness {
+    hostEl;
+    constructor(container) {
+        const el = container.querySelector('af-accordion');
+        if (!el) {
+            throw new Error('AfAccordionHarness: af-accordion element not found in container.');
+        }
+        this.hostEl = el;
+    }
+    /** Returns harnesses for all accordion items. */
+    getItems() {
+        const items = Array.from(this.hostEl.querySelectorAll('af-accordion-item'));
+        return items.map((el) => new AfAccordionItemHarness(el));
+    }
+    /** Returns the harness for the accordion item at the given index. */
+    getItem(index) {
+        const items = this.getItems();
+        if (index < 0 || index >= items.length) {
+            throw new Error(`AfAccordionHarness: index ${index} out of range (${items.length} items).`);
+        }
+        return items[index];
+    }
+    /** Returns whether the bordered variant is applied. */
+    isBordered() {
+        const wrapper = this.hostEl.querySelector('.ct-accordion');
+        return wrapper?.classList.contains('ct-accordion--bordered') ?? false;
+    }
+}
+
 /**
  * Skip-link component for keyboard-only navigation bypass.
  *
@@ -373,7 +659,7 @@ class AfSkipLinkComponent {
     target = input.required(...(ngDevMode ? [{ debugName: "target" }] : []));
     /** Visible label text shown when the link receives focus. */
     label = input('Skip to main content', ...(ngDevMode ? [{ debugName: "label" }] : []));
-    document = inject(DOCUMENT);
+    document = inject(DOCUMENT$1);
     /**
      * Moves focus to the target element so keyboard navigation
      * continues from there instead of the top of the page.
@@ -909,15 +1195,37 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImpor
         }], propDecorators: { src: [{ type: i0.Input, args: [{ isSignal: true, alias: "src", required: false }] }], name: [{ type: i0.Input, args: [{ isSignal: true, alias: "name", required: false }] }], size: [{ type: i0.Input, args: [{ isSignal: true, alias: "size", required: false }] }], alt: [{ type: i0.Input, args: [{ isSignal: true, alias: "alt", required: false }] }], status: [{ type: i0.Input, args: [{ isSignal: true, alias: "status", required: false }] }] } });
 
 /**
- * Button component from the Construct Design System
+ * Button component from the Construct Design System.
  *
- * @example
- * <af-button variant="primary" (clicked)="handleClick()">Click me</af-button>
+ * Wraps a native `<button>` element with design system tokens and
+ * variant/size modifiers.
+ *
+ * @example Basic usage
+ * <af-button variant="primary" (clicked)="save()">Save</af-button>
  *
- * @example Icon-only button
+ * @example Variants
+ * <af-button variant="secondary">Secondary</af-button>
+ * <af-button variant="ghost">Ghost</af-button>
+ * <af-button variant="outline">Outline</af-button>
+ * <af-button variant="danger">Danger</af-button>
+ * <af-button variant="accent">Accent</af-button>
+ * <af-button variant="link">Link</af-button>
+ *
+ * @example Icon-only button (ariaLabel required)
  * <af-button variant="ghost" size="sm" iconOnly ariaLabel="Delete item">
  *   <af-icon name="delete" />
  * </af-button>
+ *
+ * @example Disabled button
+ * <af-button [disabled]="true">Cannot click</af-button>
+ *
+ * @accessibility
+ * - Uses native `<button>` element — keyboard (Enter/Space) and screen reader support built-in.
+ * - Disabled state uses the native `disabled` attribute.
+ * - Icon-only buttons must provide `ariaLabel` for screen reader users.
+ *   A dev-mode warning is emitted if `ariaLabel` is missing on an icon-only button.
+ * - Focus indicator: 2px outline via `:focus-visible` (design system CSS).
+ * - Reduced motion: `transform` animation disabled via `prefers-reduced-motion`.
  */
 class AfButtonComponent {
     /** Button variant/style */
@@ -949,6 +1257,11 @@ class AfButtonComponent {
         }
         return classes.join(' ');
     }, ...(ngDevMode ? [{ debugName: "buttonClasses" }] : []));
+    iconOnlyWarning = effect(() => {
+        if (isDevMode() && this.iconOnly() && !this.ariaLabel()) {
+            console.warn('af-button: iconOnly buttons require an ariaLabel for screen readers.');
+        }
+    }, ...(ngDevMode ? [{ debugName: "iconOnlyWarning" }] : []));
     handleClick(event) {
         if (!this.disabled()) {
             this.clicked.emit(event);
@@ -983,7 +1296,88 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImpor
         }], propDecorators: { variant: [{ type: i0.Input, args: [{ isSignal: true, alias: "variant", required: false }] }], size: [{ type: i0.Input, args: [{ isSignal: true, alias: "size", required: false }] }], type: [{ type: i0.Input, args: [{ isSignal: true, alias: "type", required: false }] }], disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabled", required: false }] }], iconOnly: [{ type: i0.Input, args: [{ isSignal: true, alias: "iconOnly", required: false }] }], ariaLabel: [{ type: i0.Input, args: [{ isSignal: true, alias: "ariaLabel", required: false }] }], title: [{ type: i0.Input, args: [{ isSignal: true, alias: "title", required: false }] }], clicked: [{ type: i0.Output, args: ["clicked"] }] } });
 
 /**
- * Input field component with form control support
+ * Test harness for AfButtonComponent.
+ *
+ * Provides a semantic API for interacting with the button in tests,
+ * abstracting DOM details behind readable method names.
+ *
+ * @example
+ * const harness = new AfButtonHarness(fixture.nativeElement);
+ * expect(harness.getText()).toBe('Save');
+ * expect(harness.isDisabled()).toBe(false);
+ * harness.click();
+ */
+class AfButtonHarness {
+    hostEl;
+    constructor(container) {
+        const el = container.querySelector('af-button');
+        if (!el) {
+            throw new Error('AfButtonHarness: af-button element not found in container.');
+        }
+        this.hostEl = el;
+    }
+    /** Returns the inner native `<button>` element. */
+    getButtonElement() {
+        const btn = this.hostEl.querySelector('button');
+        if (!btn) {
+            throw new Error('AfButtonHarness: inner <button> element not found.');
+        }
+        return btn;
+    }
+    /** Returns the trimmed text content of the button. */
+    getText() {
+        return this.getButtonElement().textContent?.trim() ?? '';
+    }
+    /** Returns whether the button is disabled. */
+    isDisabled() {
+        return this.getButtonElement().disabled;
+    }
+    /** Clicks the inner button element. */
+    click() {
+        this.getButtonElement().click();
+    }
+    /** Returns the `aria-label` attribute value, or `null` if absent. */
+    getAriaLabel() {
+        return this.getButtonElement().getAttribute('aria-label');
+    }
+    /** Returns the `title` attribute value, or `null` if absent. */
+    getTitle() {
+        return this.getButtonElement().getAttribute('title');
+    }
+    /** Returns the `type` attribute of the button. */
+    getType() {
+        return this.getButtonElement().type;
+    }
+    /** Returns the full `class` attribute string of the inner button. */
+    getClasses() {
+        return this.getButtonElement().className;
+    }
+    /** Returns whether the inner button has the given CSS class. */
+    hasClass(className) {
+        return this.getButtonElement().classList.contains(className);
+    }
+}
+
+/**
+ * Injection token to override input screen-reader announcements.
+ *
+ * @example
+ * providers: [{
+ *   provide: AF_INPUT_I18N,
+ *   useValue: { required: 'Pflichtfeld' },
+ * }]
+ */
+const AF_INPUT_I18N = new InjectionToken('AfInputI18n', {
+    factory: () => ({
+        required: 'required',
+    }),
+});
+
+/**
+ * Input field component with form control support.
+ *
+ * Wraps a native `<input>` element with label, hint, error, and icon slots.
+ * Implements `ControlValueAccessor` for seamless `ngModel` and `formControl` integration.
  *
  * @example
  * <af-input
@@ -992,40 +1386,45 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImpor
  *   placeholder="name@company.com"
  *   [(ngModel)]="email"
  *   hint="We will not share this."
- * ></af-input>
+ * />
  *
  * @example
  * <af-input
  *   label="Name"
  *   [error]="nameError"
  *   required
- * ></af-input>
+ * />
  */
 class AfInputComponent {
     static nextId = 0;
-    /** Input label */
+    i18n = inject(AF_INPUT_I18N);
+    /** Input label. */
     label = input('', ...(ngDevMode ? [{ debugName: "label" }] : []));
-    /** Input type */
+    /** Input type. */
     type = input('text', ...(ngDevMode ? [{ debugName: "type" }] : []));
-    /** Placeholder text */
+    /** Placeholder text. */
     placeholder = input('', ...(ngDevMode ? [{ debugName: "placeholder" }] : []));
-    /** Hint text shown below input */
+    /** Hint text shown below input. */
     hint = input('', ...(ngDevMode ? [{ debugName: "hint" }] : []));
-    /** Error message - shows error state and message */
+    /** Error message — shows error state and message. */
     error = input('', ...(ngDevMode ? [{ debugName: "error" }] : []));
-    /** Whether input is required */
-    required = input(false, ...(ngDevMode ? [{ debugName: "required" }] : []));
-    /** Whether input is disabled */
+    /** Whether input is required. */
+    required = input(false, { ...(ngDevMode ? { debugName: "required" } : {}), transform: booleanAttribute });
+    /** Whether input is disabled. */
     disabled = model(false, ...(ngDevMode ? [{ debugName: "disabled" }] : []));
-    /** Icon position (if icon content is projected) */
+    /** Icon position (if icon content is projected). */
     iconPosition = input(null, ...(ngDevMode ? [{ debugName: "iconPosition" }] : []));
-    /** Unique input ID */
+    /** Unique input ID. */
     inputId = input(`af-input-${AfInputComponent.nextId++}`, ...(ngDevMode ? [{ debugName: "inputId" }] : []));
-    value = '';
+    /** @docs-private — internal form value managed by CVA. */
+    value = signal('', ...(ngDevMode ? [{ debugName: "value" }] : []));
     onChange = () => { };
     onTouched = () => { };
+    /** Computed hint element ID. */
     hintId = computed(() => `${this.inputId()}-hint`, ...(ngDevMode ? [{ debugName: "hintId" }] : []));
+    /** Computed error element ID. */
     errorId = computed(() => `${this.inputId()}-error`, ...(ngDevMode ? [{ debugName: "errorId" }] : []));
+    /** Computed CSS classes for the inner input. */
     inputClasses = computed(() => {
         const classes = ['ct-input'];
         if (this.iconPosition()) {
@@ -1033,45 +1432,49 @@ class AfInputComponent {
         }
         return classes.join(' ');
     }, ...(ngDevMode ? [{ debugName: "inputClasses" }] : []));
-    getAriaDescribedBy() {
+    /** Computed `aria-describedby` value linking to hint or error. */
+    ariaDescribedBy = computed(() => {
         if (this.error())
             return this.errorId();
         if (this.hint())
             return this.hintId();
         return null;
-    }
+    }, ...(ngDevMode ? [{ debugName: "ariaDescribedBy" }] : []));
     onInput(event) {
         const target = event.target;
-        this.value = target.value;
-        this.onChange(this.value);
+        this.value.set(target.value);
+        this.onChange(this.value());
     }
-    /** ControlValueAccessor implementation */
+    /** @docs-private */
     writeValue(value) {
-        this.value = value || '';
+        this.value.set(value || '');
     }
+    /** @docs-private */
     registerOnChange(fn) {
         this.onChange = fn;
     }
+    /** @docs-private */
     registerOnTouched(fn) {
         this.onTouched = fn;
     }
+    /** @docs-private */
     setDisabledState(isDisabled) {
         this.disabled.set(isDisabled);
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.2", ngImport: i0, type: AfInputComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.1.2", type: AfInputComponent, isStandalone: true, selector: "af-input", inputs: { label: { classPropertyName: "label", publicName: "label", isSignal: true, isRequired: false, transformFunction: null }, type: { classPropertyName: "type", publicName: "type", isSignal: true, isRequired: false, transformFunction: null }, placeholder: { classPropertyName: "placeholder", publicName: "placeholder", isSignal: true, isRequired: false, transformFunction: null }, hint: { classPropertyName: "hint", publicName: "hint", isSignal: true, isRequired: false, transformFunction: null }, error: { classPropertyName: "error", publicName: "error", isSignal: true, isRequired: false, transformFunction: null }, required: { classPropertyName: "required", publicName: "required", isSignal: true, isRequired: false, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "disabled", isSignal: true, isRequired: false, transformFunction: null }, iconPosition: { classPropertyName: "iconPosition", publicName: "iconPosition", isSignal: true, isRequired: false, transformFunction: null }, inputId: { classPropertyName: "inputId", publicName: "inputId", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { disabled: "disabledChange" }, providers: [
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.1.2", type: AfInputComponent, isStandalone: true, selector: "af-input", inputs: { label: { classPropertyName: "label", publicName: "label", isSignal: true, isRequired: false, transformFunction: null }, type: { classPropertyName: "type", publicName: "type", isSignal: true, isRequired: false, transformFunction: null }, placeholder: { classPropertyName: "placeholder", publicName: "placeholder", isSignal: true, isRequired: false, transformFunction: null }, hint: { classPropertyName: "hint", publicName: "hint", isSignal: true, isRequired: false, transformFunction: null }, error: { classPropertyName: "error", publicName: "error", isSignal: true, isRequired: false, transformFunction: null }, required: { classPropertyName: "required", publicName: "required", isSignal: true, isRequired: false, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "disabled", isSignal: true, isRequired: false, transformFunction: null }, iconPosition: { classPropertyName: "iconPosition", publicName: "iconPosition", isSignal: true, isRequired: false, transformFunction: null }, inputId: { classPropertyName: "inputId", publicName: "inputId", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { disabled: "disabledChange" }, host: { styleAttribute: "display: block" }, providers: [
             {
                 provide: NG_VALUE_ACCESSOR,
                 useExisting: forwardRef(() => AfInputComponent),
-                multi: true
-            }
+                multi: true,
+            },
         ], ngImport: i0, template: `
     <div class="ct-field" [class.ct-field--error]="error()">
       @if (label()) {
         <label class="ct-field__label" [attr.for]="inputId()">
           {{ label() }}
           @if (required()) {
-            <span aria-label="required"> *</span>
+            <span [attr.aria-label]="i18n.required"> *</span>
           }
         </label>
       }
@@ -1080,7 +1483,7 @@ class AfInputComponent {
         <div class="ct-input-wrap">
           @if (iconPosition() === 'left') {
             <span class="ct-input__icon" aria-hidden="true">
-              <ng-content select="[icon]"></ng-content>
+              <ng-content select="[icon]" />
             </span>
           }
           <input
@@ -1090,21 +1493,19 @@ class AfInputComponent {
             [disabled]="disabled()"
             [required]="required()"
             [attr.aria-invalid]="error() ? true : null"
-            [attr.aria-describedby]="getAriaDescribedBy()"
+            [attr.aria-describedby]="ariaDescribedBy()"
             [class]="inputClasses()"
-            [value]="value"
+            [value]="value()"
             (input)="onInput($event)"
             (blur)="onTouched()"
           />
           @if (iconPosition() === 'right') {
             <span class="ct-input__icon" aria-hidden="true">
-              <ng-content select="[icon]"></ng-content>
+              <ng-content select="[icon]" />
             </span>
           }
         </div>
-      }
-
-      @if (!iconPosition()) {
+      } @else {
         <input
           [id]="inputId()"
           [type]="type()"
@@ -1112,9 +1513,9 @@ class AfInputComponent {
           [disabled]="disabled()"
           [required]="required()"
           [attr.aria-invalid]="error() ? true : null"
-          [attr.aria-describedby]="getAriaDescribedBy()"
-          class="ct-input"
-          [value]="value"
+          [attr.aria-describedby]="ariaDescribedBy()"
+          [class]="inputClasses()"
+          [value]="value()"
           (input)="onInput($event)"
           (blur)="onTouched()"
         />
@@ -1127,28 +1528,35 @@ class AfInputComponent {
       }
 
       @if (error()) {
-        <div class="ct-field__error" [id]="errorId()">
+        <div class="ct-field__error" role="alert" [id]="errorId()">
           {{ error() }}
         </div>
       }
     </div>
-  `, isInline: true, styles: [":host{display:block}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+  `, isInline: true, changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImport: i0, type: AfInputComponent, decorators: [{
             type: Component,
-            args: [{ selector: 'af-input', changeDetection: ChangeDetectionStrategy.OnPush, providers: [
+            args: [{
+                    selector: 'af-input',
+                    changeDetection: ChangeDetectionStrategy.OnPush,
+                    providers: [
                         {
                             provide: NG_VALUE_ACCESSOR,
                             useExisting: forwardRef(() => AfInputComponent),
-                            multi: true
-                        }
-                    ], template: `
+                            multi: true,
+                        },
+                    ],
+                    host: {
+                        style: 'display: block',
+                    },
+                    template: `
     <div class="ct-field" [class.ct-field--error]="error()">
       @if (label()) {
         <label class="ct-field__label" [attr.for]="inputId()">
           {{ label() }}
           @if (required()) {
-            <span aria-label="required"> *</span>
+            <span [attr.aria-label]="i18n.required"> *</span>
           }
         </label>
       }
@@ -1157,7 +1565,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImpor
         <div class="ct-input-wrap">
           @if (iconPosition() === 'left') {
             <span class="ct-input__icon" aria-hidden="true">
-              <ng-content select="[icon]"></ng-content>
+              <ng-content select="[icon]" />
             </span>
           }
           <input
@@ -1167,21 +1575,19 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImpor
             [disabled]="disabled()"
             [required]="required()"
             [attr.aria-invalid]="error() ? true : null"
-            [attr.aria-describedby]="getAriaDescribedBy()"
+            [attr.aria-describedby]="ariaDescribedBy()"
             [class]="inputClasses()"
-            [value]="value"
+            [value]="value()"
             (input)="onInput($event)"
             (blur)="onTouched()"
           />
           @if (iconPosition() === 'right') {
             <span class="ct-input__icon" aria-hidden="true">
-              <ng-content select="[icon]"></ng-content>
+              <ng-content select="[icon]" />
             </span>
           }
         </div>
-      }
-
-      @if (!iconPosition()) {
+      } @else {
         <input
           [id]="inputId()"
           [type]="type()"
@@ -1189,9 +1595,9 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImpor
           [disabled]="disabled()"
           [required]="required()"
           [attr.aria-invalid]="error() ? true : null"
-          [attr.aria-describedby]="getAriaDescribedBy()"
-          class="ct-input"
-          [value]="value"
+          [attr.aria-describedby]="ariaDescribedBy()"
+          [class]="inputClasses()"
+          [value]="value()"
           (input)="onInput($event)"
           (blur)="onTouched()"
         />
@@ -1204,14 +1610,123 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImpor
       }
 
       @if (error()) {
-        <div class="ct-field__error" [id]="errorId()">
+        <div class="ct-field__error" role="alert" [id]="errorId()">
           {{ error() }}
         </div>
       }
     </div>
-  `, styles: [":host{display:block}\n"] }]
+  `,
+                }]
         }], propDecorators: { label: [{ type: i0.Input, args: [{ isSignal: true, alias: "label", required: false }] }], type: [{ type: i0.Input, args: [{ isSignal: true, alias: "type", required: false }] }], placeholder: [{ type: i0.Input, args: [{ isSignal: true, alias: "placeholder", required: false }] }], hint: [{ type: i0.Input, args: [{ isSignal: true, alias: "hint", required: false }] }], error: [{ type: i0.Input, args: [{ isSignal: true, alias: "error", required: false }] }], required: [{ type: i0.Input, args: [{ isSignal: true, alias: "required", required: false }] }], disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabled", required: false }] }, { type: i0.Output, args: ["disabledChange"] }], iconPosition: [{ type: i0.Input, args: [{ isSignal: true, alias: "iconPosition", required: false }] }], inputId: [{ type: i0.Input, args: [{ isSignal: true, alias: "inputId", required: false }] }] } });
 
+/**
+ * Test harness for AfInputComponent.
+ *
+ * Provides a semantic API for interacting with the input in tests,
+ * abstracting DOM details behind readable method names.
+ *
+ * @example
+ * const harness = new AfInputHarness(fixture.nativeElement);
+ * expect(harness.getValue()).toBe('');
+ * harness.setValue('hello');
+ * expect(harness.getValue()).toBe('hello');
+ */
+class AfInputHarness {
+    hostEl;
+    constructor(container) {
+        const el = container.querySelector('af-input');
+        if (!el) {
+            throw new Error('AfInputHarness: af-input element not found in container.');
+        }
+        this.hostEl = el;
+    }
+    /** Returns the inner native `<input>` element. */
+    getInputElement() {
+        const input = this.hostEl.querySelector('input');
+        if (!input) {
+            throw new Error('AfInputHarness: inner <input> element not found.');
+        }
+        return input;
+    }
+    /** Returns the current value of the input. */
+    getValue() {
+        return this.getInputElement().value;
+    }
+    /** Sets the input value and dispatches an `input` event. */
+    setValue(value) {
+        const input = this.getInputElement();
+        input.value = value;
+        input.dispatchEvent(new Event('input', { bubbles: true }));
+    }
+    /** Returns the label text, or `null` if no label is rendered. */
+    getLabel() {
+        const label = this.hostEl.querySelector('.ct-field__label');
+        return label?.textContent?.trim() ?? null;
+    }
+    /** Returns the hint text, or `null` if no hint is rendered. */
+    getHint() {
+        const hint = this.hostEl.querySelector('.ct-field__hint');
+        return hint?.textContent?.trim() ?? null;
+    }
+    /** Returns the error text, or `null` if no error is rendered. */
+    getError() {
+        const error = this.hostEl.querySelector('.ct-field__error');
+        return error?.textContent?.trim() ?? null;
+    }
+    /** Returns whether the input is disabled. */
+    isDisabled() {
+        return this.getInputElement().disabled;
+    }
+    /** Returns whether the input is required. */
+    isRequired() {
+        return this.getInputElement().required;
+    }
+    /** Returns whether `aria-invalid` is set to `"true"`. */
+    isInvalid() {
+        return this.getInputElement().getAttribute('aria-invalid') === 'true';
+    }
+    /** Returns the `type` attribute of the input. */
+    getType() {
+        return this.getInputElement().type;
+    }
+    /** Returns the `placeholder` attribute of the input. */
+    getPlaceholder() {
+        return this.getInputElement().placeholder;
+    }
+    /** Returns the `aria-describedby` attribute value, or `null` if absent. */
+    getAriaDescribedBy() {
+        return this.getInputElement().getAttribute('aria-describedby');
+    }
+    /** Focuses the input element. */
+    focus() {
+        this.getInputElement().focus();
+    }
+    /** Blurs the input element and dispatches a `blur` event. */
+    blur() {
+        this.getInputElement().dispatchEvent(new Event('blur', { bubbles: true }));
+    }
+    /** Returns the `id` attribute of the input. */
+    getId() {
+        return this.getInputElement().id;
+    }
+    /** Returns whether the field wrapper has the error modifier class. */
+    hasFieldError() {
+        return this.hostEl.querySelector('.ct-field--error') !== null;
+    }
+    /** Returns whether an icon wrapper is rendered. */
+    hasIcon() {
+        return this.hostEl.querySelector('.ct-input__icon') !== null;
+    }
+    /** Returns the full `class` attribute string of the inner input. */
+    getClasses() {
+        return this.getInputElement().className;
+    }
+    /** Returns whether the inner input has the given CSS class. */
+    hasClass(className) {
+        return this.getInputElement().classList.contains(className);
+    }
+}
+
 /**
  * Select dropdown component with form control support
  *
@@ -3579,164 +4094,493 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImpor
   `, styles: [":host{display:block}\n"] }]
         }], propDecorators: { items: [{ type: i0.Input, args: [{ isSignal: true, alias: "items", required: false }] }] } });
 
+const MONTH_NAMES = [
+    'January',
+    'February',
+    'March',
+    'April',
+    'May',
+    'June',
+    'July',
+    'August',
+    'September',
+    'October',
+    'November',
+    'December',
+];
+const MONTH_SHORT = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const WEEKDAY_LABELS = ['Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa', 'Su'];
 /**
- * Datepicker component with calendar popup
+ * Datepicker component with calendar popup, month/year views, range selection,
+ * min/max constraints, disabled dates, and full keyboard navigation.
+ *
+ * Implements WAI-ARIA Date Picker Dialog pattern with roving tabindex.
  *
  * @example
  * <af-datepicker
- *   label="Select date"
+ *   label="Start date"
  *   placeholder="Pick a date"
- *   [(ngModel)]="selectedDate">
- * </af-datepicker>
+ *   [(ngModel)]="selectedDate"
+ *   [min]="minDate"
+ *   [max]="maxDate"
+ *   hint="Choose a date within the project timeline"
+ * />
+ *
+ * @example
+ * <af-datepicker
+ *   label="Period"
+ *   mode="range"
+ *   [(ngModel)]="dateRange"
+ *   valueFormat="iso"
+ * />
  */
 class AfDatepickerComponent {
     static nextId = 0;
-    /** Input label */
+    // ── Public Inputs ────────────────────────────────────────────
+    /** Field label */
     label = input('', ...(ngDevMode ? [{ debugName: "label" }] : []));
-    /** Placeholder text */
+    /** Input placeholder text */
     placeholder = input('Select date', ...(ngDevMode ? [{ debugName: "placeholder" }] : []));
-    /** Whether datepicker is disabled */
+    /** Whether the datepicker is disabled */
     disabled = model(false, ...(ngDevMode ? [{ debugName: "disabled" }] : []));
-    /** Date format for display */
+    /** Display format for the selected date */
     dateFormat = input('MMM dd, yyyy', ...(ngDevMode ? [{ debugName: "dateFormat" }] : []));
-    /** Unique input ID */
+    /** Unique ID for the input element */
     inputId = input(`af-datepicker-${AfDatepickerComponent.nextId++}`, ...(ngDevMode ? [{ debugName: "inputId" }] : []));
-    /** Selected date change event */
+    /** Minimum selectable date */
+    min = input(null, ...(ngDevMode ? [{ debugName: "min" }] : []));
+    /** Maximum selectable date */
+    max = input(null, ...(ngDevMode ? [{ debugName: "max" }] : []));
+    /** Array of specific dates that cannot be selected */
+    disabledDates = input([], ...(ngDevMode ? [{ debugName: "disabledDates" }] : []));
+    /**
+     * Predicate function to determine if a date is selectable.
+     * Return `true` to allow selection, `false` to disable.
+     */
+    dateFilter = input(null, ...(ngDevMode ? [{ debugName: "dateFilter" }] : []));
+    /** Hint text displayed below the input */
+    hint = input('', ...(ngDevMode ? [{ debugName: "hint" }] : []));
+    /** Error message — displays error state and message */
+    error = input('', ...(ngDevMode ? [{ debugName: "error" }] : []));
+    /** Whether the field is required */
+    required = input(false, ...(ngDevMode ? [{ debugName: "required" }] : []));
+    /** Selection mode: single date or date range */
+    mode = input('single', ...(ngDevMode ? [{ debugName: "mode" }] : []));
+    /**
+     * Value format for ControlValueAccessor.
+     * `'date'` emits `Date` objects, `'iso'` emits ISO date strings (`yyyy-MM-dd`).
+     */
+    valueFormat = input('date', ...(ngDevMode ? [{ debugName: "valueFormat" }] : []));
+    /** Emitted when a single date is selected */
     dateChange = output();
-    inputRef = viewChild('input', ...(ngDevMode ? [{ debugName: "inputRef" }] : []));
-    popoverRef = viewChild('popover', ...(ngDevMode ? [{ debugName: "popoverRef" }] : []));
-    weekdayLabels = ['Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa', 'Su'];
-    monthNames = [
-        'January', 'February', 'March', 'April', 'May', 'June',
-        'July', 'August', 'September', 'October', 'November', 'December'
-    ];
+    /** Emitted when a date range is selected (range mode only) */
+    rangeChange = output();
+    // ── Template References ──────────────────────────────────────
+    inputRef = viewChild('inputEl', ...(ngDevMode ? [{ debugName: "inputRef" }] : []));
+    popoverRef = viewChild('popoverEl', ...(ngDevMode ? [{ debugName: "popoverRef" }] : []));
+    // ── Constants ────────────────────────────────────────────────
+    weekdayLabels = WEEKDAY_LABELS;
+    weekdayFullLabels = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'];
+    // ── Internal State ───────────────────────────────────────────
     selectedDate = signal(null, ...(ngDevMode ? [{ debugName: "selectedDate" }] : []));
+    rangeStart = signal(null, ...(ngDevMode ? [{ debugName: "rangeStart" }] : []));
+    rangeEnd = signal(null, ...(ngDevMode ? [{ debugName: "rangeEnd" }] : []));
+    rangeSelecting = signal(false, ...(ngDevMode ? [{ debugName: "rangeSelecting" }] : []));
     currentMonth = signal(new Date().getMonth(), ...(ngDevMode ? [{ debugName: "currentMonth" }] : []));
     currentYear = signal(new Date().getFullYear(), ...(ngDevMode ? [{ debugName: "currentYear" }] : []));
     isOpen = signal(false, ...(ngDevMode ? [{ debugName: "isOpen" }] : []));
     focusedDate = signal(null, ...(ngDevMode ? [{ debugName: "focusedDate" }] : []));
+    currentView = signal('days', ...(ngDevMode ? [{ debugName: "currentView" }] : []));
+    focusedMonth = signal(new Date().getMonth(), ...(ngDevMode ? [{ debugName: "focusedMonth" }] : []));
+    focusedYear = signal(new Date().getFullYear(), ...(ngDevMode ? [{ debugName: "focusedYear" }] : []));
+    yearPageStart = signal(Math.floor(new Date().getFullYear() / 12) * 12, ...(ngDevMode ? [{ debugName: "yearPageStart" }] : []));
     onChange = () => { };
     onTouched = () => { };
-    calendarDays = computed(() => {
-        return this.generateCalendarDays();
-    }, ...(ngDevMode ? [{ debugName: "calendarDays" }] : []));
-    formattedDate = computed(() => {
-        const date = this.selectedDate();
-        if (!date)
-            return '';
-        return this.formatDate(date);
-    }, ...(ngDevMode ? [{ debugName: "formattedDate" }] : []));
+    onValidatorChange = () => { };
+    // ── Computed ─────────────────────────────────────────────────
+    parsedMin = computed(() => this.parseDate(this.min()), ...(ngDevMode ? [{ debugName: "parsedMin" }] : []));
+    parsedMax = computed(() => this.parseDate(this.max()), ...(ngDevMode ? [{ debugName: "parsedMax" }] : []));
     popoverId = computed(() => `${this.inputId()}-popover`, ...(ngDevMode ? [{ debugName: "popoverId" }] : []));
-    toggle() {
-        if (this.isOpen()) {
-            this.close();
-        }
-        else {
-            this.open();
+    hintId = computed(() => `${this.inputId()}-hint`, ...(ngDevMode ? [{ debugName: "hintId" }] : []));
+    errorId = computed(() => `${this.inputId()}-error`, ...(ngDevMode ? [{ debugName: "errorId" }] : []));
+    ariaDescribedBy = computed(() => {
+        if (this.error())
+            return this.errorId();
+        if (this.hint())
+            return this.hintId();
+        return null;
+    }, ...(ngDevMode ? [{ debugName: "ariaDescribedBy" }] : []));
+    dialogAriaLabel = computed(() => {
+        if (this.mode() === 'range')
+            return 'Choose date range';
+        return 'Choose date';
+    }, ...(ngDevMode ? [{ debugName: "dialogAriaLabel" }] : []));
+    headerTitle = computed(() => {
+        switch (this.currentView()) {
+            case 'days':
+                return `${MONTH_NAMES[this.currentMonth()]} ${this.currentYear()}`;
+            case 'months':
+                return `${this.currentYear()}`;
+            case 'years':
+                return `${this.yearPageStart()} – ${this.yearPageStart() + 11}`;
+        }
+    }, ...(ngDevMode ? [{ debugName: "headerTitle" }] : []));
+    titleAriaLabel = computed(() => {
+        switch (this.currentView()) {
+            case 'days':
+                return 'Switch to month view';
+            case 'months':
+                return 'Switch to year view';
+            case 'years':
+                return null;
+        }
+    }, ...(ngDevMode ? [{ debugName: "titleAriaLabel" }] : []));
+    prevButtonAriaLabel = computed(() => {
+        switch (this.currentView()) {
+            case 'days':
+                return 'Previous month';
+            case 'months':
+                return 'Previous year';
+            case 'years':
+                return 'Previous 12 years';
+        }
+    }, ...(ngDevMode ? [{ debugName: "prevButtonAriaLabel" }] : []));
+    nextButtonAriaLabel = computed(() => {
+        switch (this.currentView()) {
+            case 'days':
+                return 'Next month';
+            case 'months':
+                return 'Next year';
+            case 'years':
+                return 'Next 12 years';
+        }
+    }, ...(ngDevMode ? [{ debugName: "nextButtonAriaLabel" }] : []));
+    gridAriaLabel = computed(() => `${MONTH_NAMES[this.currentMonth()]} ${this.currentYear()}`, ...(ngDevMode ? [{ debugName: "gridAriaLabel" }] : []));
+    hasClearableValue = computed(() => {
+        if (this.mode() === 'range') {
+            return this.rangeStart() !== null || this.rangeEnd() !== null;
+        }
+        return this.selectedDate() !== null;
+    }, ...(ngDevMode ? [{ debugName: "hasClearableValue" }] : []));
+    formattedValue = computed(() => {
+        if (this.mode() === 'range') {
+            const start = this.rangeStart();
+            const end = this.rangeEnd();
+            if (!start && !end)
+                return '';
+            const startStr = start ? this.formatDate(start) : '...';
+            const endStr = end ? this.formatDate(end) : '...';
+            return `${startStr} – ${endStr}`;
         }
-    }
-    selectDate(date) {
-        this.selectedDate.set(date);
-        this.focusedDate.set(date);
-        this.onChange(date);
-        this.dateChange.emit(date);
-        this.close(true);
-    }
-    previousMonth() {
-        this.shiftMonth(-1);
-    }
-    nextMonth() {
-        this.shiftMonth(1);
-    }
-    generateCalendarDays() {
+        const date = this.selectedDate();
+        return date ? this.formatDate(date) : '';
+    }, ...(ngDevMode ? [{ debugName: "formattedValue" }] : []));
+    isTodayDisabled = computed(() => this.isDateDisabled(new Date()), ...(ngDevMode ? [{ debugName: "isTodayDisabled" }] : []));
+    calendarDays = computed(() => {
         const year = this.currentYear();
         const month = this.currentMonth();
-        const firstDay = new Date(year, month, 1);
-        const lastDay = new Date(year, month + 1, 0);
         const today = new Date();
         const selected = this.selectedDate();
+        const rStart = this.rangeStart();
+        const rEnd = this.rangeEnd();
+        const previewEnd = this.mode() === 'range' && this.rangeSelecting() ? this.focusedDate() : null;
+        const effectiveEnd = rEnd ?? previewEnd;
+        const firstDay = new Date(year, month, 1);
+        const lastDay = new Date(year, month + 1, 0);
         const days = [];
-        // Get day of week (0 = Sunday, adjust to Monday = 0)
-        let startDay = firstDay.getDay() - 1;
-        if (startDay < 0)
-            startDay = 6;
-        // Previous month days
-        const prevMonthLastDay = new Date(year, month, 0).getDate();
-        for (let i = startDay - 1; i >= 0; i--) {
-            const date = new Date(year, month - 1, prevMonthLastDay - i);
-            days.push({
-                date,
-                isCurrentMonth: false,
-                isToday: this.isSameDay(date, today),
-                isSelected: selected ? this.isSameDay(date, selected) : false
-            });
+        let startPad = firstDay.getDay() - 1;
+        if (startPad < 0)
+            startPad = 6;
+        const prevLast = new Date(year, month, 0).getDate();
+        for (let i = startPad - 1; i >= 0; i--) {
+            days.push(this.buildDay(new Date(year, month - 1, prevLast - i), false, today, selected, rStart, effectiveEnd));
         }
-        // Current month days
         for (let i = 1; i <= lastDay.getDate(); i++) {
-            const date = new Date(year, month, i);
-            days.push({
-                date,
-                isCurrentMonth: true,
-                isToday: this.isSameDay(date, today),
-                isSelected: selected ? this.isSameDay(date, selected) : false
-            });
+            days.push(this.buildDay(new Date(year, month, i), true, today, selected, rStart, effectiveEnd));
         }
-        // Next month days to fill grid (6 rows * 7 days = 42)
-        const remainingDays = 42 - days.length;
-        for (let i = 1; i <= remainingDays; i++) {
-            const date = new Date(year, month + 1, i);
-            days.push({
-                date,
-                isCurrentMonth: false,
-                isToday: this.isSameDay(date, today),
-                isSelected: selected ? this.isSameDay(date, selected) : false
-            });
+        const remaining = 42 - days.length;
+        for (let i = 1; i <= remaining; i++) {
+            days.push(this.buildDay(new Date(year, month + 1, i), false, today, selected, rStart, effectiveEnd));
         }
         return days;
+    }, ...(ngDevMode ? [{ debugName: "calendarDays" }] : []));
+    monthItems = computed(() => {
+        const year = this.currentYear();
+        const selected = this.selectedDate();
+        const min = this.parsedMin();
+        const max = this.parsedMax();
+        return Array.from({ length: 12 }, (_, i) => {
+            const isDisabled = this.isMonthDisabled(year, i, min, max);
+            return {
+                index: i,
+                label: MONTH_NAMES[i],
+                shortLabel: MONTH_SHORT[i],
+                isSelected: selected ? selected.getMonth() === i && selected.getFullYear() === year : false,
+                isDisabled,
+            };
+        });
+    }, ...(ngDevMode ? [{ debugName: "monthItems" }] : []));
+    yearItems = computed(() => {
+        const start = this.yearPageStart();
+        const selected = this.selectedDate();
+        const min = this.parsedMin();
+        const max = this.parsedMax();
+        return Array.from({ length: 12 }, (_, i) => {
+            const value = start + i;
+            return {
+                value,
+                isSelected: selected ? selected.getFullYear() === value : false,
+                isDisabled: this.isYearDisabled(value, min, max),
+            };
+        });
+    }, ...(ngDevMode ? [{ debugName: "yearItems" }] : []));
+    // ── Open / Close ─────────────────────────────────────────────
+    toggle() {
+        if (this.isOpen()) {
+            this.close(true);
+        }
+        else {
+            this.open();
+        }
     }
-    getDayTabIndex(day) {
-        const focused = this.focusedDate();
-        if (focused && this.isSameDay(day.date, focused))
-            return 0;
-        if (!focused && day.isSelected)
-            return 0;
-        return -1;
-    }
-    getDateKey(date) {
-        const year = date.getFullYear();
-        const month = String(date.getMonth() + 1).padStart(2, '0');
-        const day = String(date.getDate()).padStart(2, '0');
-        return `${year}-${month}-${day}`;
-    }
-    onInputKeydown(event) {
-        if (this.disabled())
+    /** Opens the calendar popover */
+    open() {
+        if (this.disabled() || this.isOpen())
             return;
-        if (event.key === 'ArrowDown' || event.key === 'Enter' || event.key === ' ') {
-            event.preventDefault();
-            this.open();
+        const selected = this.selectedDate();
+        const focusDate = selected ?? new Date();
+        this.currentMonth.set(focusDate.getMonth());
+        this.currentYear.set(focusDate.getFullYear());
+        this.focusedDate.set(focusDate);
+        this.focusedMonth.set(focusDate.getMonth());
+        this.focusedYear.set(focusDate.getFullYear());
+        this.currentView.set('days');
+        this.isOpen.set(true);
+        queueMicrotask(() => this.focusDayButton(focusDate));
+    }
+    /** Closes the calendar popover */
+    close(returnFocus = false) {
+        if (!this.isOpen())
+            return;
+        this.isOpen.set(false);
+        this.onTouched();
+        if (returnFocus) {
+            this.inputRef()?.nativeElement.focus();
         }
-        else if (event.key === 'Escape') {
-            event.preventDefault();
+    }
+    // ── Day Selection ────────────────────────────────────────────
+    /** Handles click on a calendar day */
+    onDayClick(day) {
+        if (day.isDisabled || day.isUnavailable)
+            return;
+        if (this.mode() === 'range') {
+            this.selectRangeDate(day.date);
+        }
+        else {
+            this.selectSingleDate(day.date);
+        }
+    }
+    /** Selects a single date and closes the popover */
+    selectSingleDate(date) {
+        this.selectedDate.set(date);
+        this.focusedDate.set(date);
+        this.emitSingleValue(date);
+        this.dateChange.emit(date);
+        this.close(true);
+    }
+    /** Handles range date selection (two-click: start then end) */
+    selectRangeDate(date) {
+        if (!this.rangeSelecting()) {
+            this.rangeStart.set(date);
+            this.rangeEnd.set(null);
+            this.rangeSelecting.set(true);
+            this.focusedDate.set(date);
+        }
+        else {
+            let start = this.rangeStart();
+            let end = date;
+            if (this.compareDays(end, start) < 0) {
+                [start, end] = [end, start];
+            }
+            this.rangeStart.set(start);
+            this.rangeEnd.set(end);
+            this.rangeSelecting.set(false);
+            this.emitRangeValue(start, end);
+            this.rangeChange.emit({ start, end });
             this.close(true);
         }
     }
-    onGridKeydown(event) {
+    /** Navigates to today and selects it (single mode) or focuses it */
+    goToToday() {
+        const today = new Date();
+        if (this.isDateDisabled(today))
+            return;
+        this.currentMonth.set(today.getMonth());
+        this.currentYear.set(today.getFullYear());
+        this.focusedDate.set(today);
+        if (this.mode() === 'single') {
+            this.selectSingleDate(today);
+        }
+        else {
+            this.selectRangeDate(today);
+        }
+    }
+    /** Clears the selected value */
+    clearValue(event) {
+        event.stopPropagation();
+        if (this.mode() === 'range') {
+            this.rangeStart.set(null);
+            this.rangeEnd.set(null);
+            this.rangeSelecting.set(false);
+            this.emitRangeValue(null, null);
+        }
+        else {
+            this.selectedDate.set(null);
+            this.emitSingleValue(null);
+        }
+        this.inputRef()?.nativeElement.focus();
+    }
+    // ── View Navigation ──────────────────────────────────────────
+    /** Drills up: days -> months -> years */
+    drillUp() {
+        const view = this.currentView();
+        if (view === 'days') {
+            this.focusedMonth.set(this.currentMonth());
+            this.currentView.set('months');
+            queueMicrotask(() => this.focusMonthButton(this.focusedMonth()));
+        }
+        else if (view === 'months') {
+            this.focusedYear.set(this.currentYear());
+            this.yearPageStart.set(Math.floor(this.currentYear() / 12) * 12);
+            this.currentView.set('years');
+            queueMicrotask(() => this.focusYearButton(this.focusedYear()));
+        }
+    }
+    /** Navigates to previous period based on current view */
+    navigatePrevious() {
+        switch (this.currentView()) {
+            case 'days':
+                this.shiftMonth(-1);
+                break;
+            case 'months':
+                this.currentYear.update((y) => y - 1);
+                break;
+            case 'years':
+                this.yearPageStart.update((s) => s - 12);
+                break;
+        }
+    }
+    /** Navigates to next period based on current view */
+    navigateNext() {
+        switch (this.currentView()) {
+            case 'days':
+                this.shiftMonth(1);
+                break;
+            case 'months':
+                this.currentYear.update((y) => y + 1);
+                break;
+            case 'years':
+                this.yearPageStart.update((s) => s + 12);
+                break;
+        }
+    }
+    /** Selects a month from the month view and switches to days */
+    selectMonth(monthIndex) {
+        this.currentMonth.set(monthIndex);
+        this.focusedMonth.set(monthIndex);
+        this.currentView.set('days');
+        const focusDate = new Date(this.currentYear(), monthIndex, 1);
+        this.focusedDate.set(focusDate);
+        queueMicrotask(() => this.focusDayButton(focusDate));
+    }
+    /** Selects a year from the year view and switches to months */
+    selectYear(year) {
+        this.currentYear.set(year);
+        this.focusedYear.set(year);
+        this.currentView.set('months');
+        queueMicrotask(() => this.focusMonthButton(this.focusedMonth()));
+    }
+    // ── Day Helpers for Template ─────────────────────────────────
+    /** Returns true if the given day matches the keyboard-focused date */
+    isDayHighlighted(day) {
+        const focused = this.focusedDate();
+        return focused !== null && this.isSameDay(day.date, focused);
+    }
+    /** Returns the tabindex for a day button (roving tabindex pattern) */
+    getDayTabIndex(day) {
+        const focused = this.focusedDate();
+        if (focused && this.isSameDay(day.date, focused))
+            return 0;
+        if (!focused && day.isSelected)
+            return 0;
+        return -1;
+    }
+    /** Returns true if the given month index matches the keyboard-focused month */
+    isMonthHighlighted(monthIndex) {
+        return this.currentView() === 'months' && this.focusedMonth() === monthIndex;
+    }
+    /** Returns the tabindex for a month button */
+    getMonthTabIndex(monthIndex) {
+        return this.focusedMonth() === monthIndex ? 0 : -1;
+    }
+    /** Returns true if the given year matches the keyboard-focused year */
+    isYearHighlighted(year) {
+        return this.currentView() === 'years' && this.focusedYear() === year;
+    }
+    /** Returns the tabindex for a year button */
+    getYearTabIndex(year) {
+        return this.focusedYear() === year ? 0 : -1;
+    }
+    /** Returns a date key string for DOM identification */
+    getDateKey(date) {
+        return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+    }
+    // ── Keyboard Handlers ────────────────────────────────────────
+    onInputKeydown(event) {
+        if (this.disabled())
+            return;
+        switch (event.key) {
+            case 'ArrowDown':
+            case 'Enter':
+            case ' ':
+                event.preventDefault();
+                this.open();
+                break;
+            case 'Escape':
+                if (this.isOpen()) {
+                    event.preventDefault();
+                    this.close(true);
+                }
+                break;
+            case 'Delete':
+            case 'Backspace':
+                if (this.hasClearableValue()) {
+                    event.preventDefault();
+                    this.clearValue(event);
+                }
+                break;
+        }
+    }
+    /** Keyboard navigation within the day grid */
+    onDayGridKeydown(event) {
         if (!this.isOpen())
             return;
-        const focused = this.focusedDate() || this.selectedDate() || new Date(this.currentYear(), this.currentMonth(), 1);
+        const focused = this.focusedDate() ??
+            this.selectedDate() ??
+            new Date(this.currentYear(), this.currentMonth(), 1);
         let nextDate = null;
         switch (event.key) {
             case 'ArrowRight':
-                nextDate = this.addDays(focused, 1);
+                nextDate = this.findNextEnabledDate(focused, 1);
                 break;
             case 'ArrowLeft':
-                nextDate = this.addDays(focused, -1);
+                nextDate = this.findNextEnabledDate(focused, -1);
                 break;
             case 'ArrowDown':
-                nextDate = this.addDays(focused, 7);
+                nextDate = this.findNextEnabledDate(focused, 7);
                 break;
             case 'ArrowUp':
-                nextDate = this.addDays(focused, -7);
+                nextDate = this.findNextEnabledDate(focused, -7);
                 break;
             case 'Home':
                 nextDate = this.addDays(focused, -this.getWeekdayIndex(focused));
@@ -3745,15 +4589,17 @@ class AfDatepickerComponent {
                 nextDate = this.addDays(focused, 6 - this.getWeekdayIndex(focused));
                 break;
             case 'PageUp':
-                nextDate = this.addMonths(focused, -1);
+                nextDate = event.shiftKey ? this.addYears(focused, -1) : this.addMonths(focused, -1);
                 break;
             case 'PageDown':
-                nextDate = this.addMonths(focused, 1);
+                nextDate = event.shiftKey ? this.addYears(focused, 1) : this.addMonths(focused, 1);
                 break;
             case 'Enter':
             case ' ':
                 event.preventDefault();
-                this.selectDate(focused);
+                if (!this.isDateDisabled(focused)) {
+                    this.onDayClick({ date: focused });
+                }
                 return;
             case 'Escape':
                 event.preventDefault();
@@ -3767,10 +4613,100 @@ class AfDatepickerComponent {
             this.setFocusedDate(nextDate);
         }
     }
-    onEscape() {
-        if (this.isOpen()) {
-            this.close(true);
+    /** Keyboard navigation within the month grid */
+    onMonthGridKeydown(event) {
+        let nextMonth = this.focusedMonth();
+        switch (event.key) {
+            case 'ArrowRight':
+                nextMonth = Math.min(11, nextMonth + 1);
+                break;
+            case 'ArrowLeft':
+                nextMonth = Math.max(0, nextMonth - 1);
+                break;
+            case 'ArrowDown':
+                nextMonth = Math.min(11, nextMonth + 3);
+                break;
+            case 'ArrowUp':
+                nextMonth = Math.max(0, nextMonth - 3);
+                break;
+            case 'Home':
+                nextMonth = 0;
+                break;
+            case 'End':
+                nextMonth = 11;
+                break;
+            case 'Enter':
+            case ' ':
+                event.preventDefault();
+                if (!this.isMonthDisabled(this.currentYear(), nextMonth, this.parsedMin(), this.parsedMax())) {
+                    this.selectMonth(nextMonth);
+                }
+                return;
+            case 'Escape':
+                event.preventDefault();
+                this.currentView.set('days');
+                queueMicrotask(() => this.focusDayButton(this.focusedDate() ?? new Date()));
+                return;
+            default:
+                return;
+        }
+        event.preventDefault();
+        this.focusedMonth.set(nextMonth);
+        queueMicrotask(() => this.focusMonthButton(nextMonth));
+    }
+    /** Keyboard navigation within the year grid */
+    onYearGridKeydown(event) {
+        let nextYear = this.focusedYear();
+        const pageStart = this.yearPageStart();
+        switch (event.key) {
+            case 'ArrowRight':
+                nextYear += 1;
+                break;
+            case 'ArrowLeft':
+                nextYear -= 1;
+                break;
+            case 'ArrowDown':
+                nextYear += 3;
+                break;
+            case 'ArrowUp':
+                nextYear -= 3;
+                break;
+            case 'Home':
+                nextYear = pageStart;
+                break;
+            case 'End':
+                nextYear = pageStart + 11;
+                break;
+            case 'PageUp':
+                nextYear -= 12;
+                break;
+            case 'PageDown':
+                nextYear += 12;
+                break;
+            case 'Enter':
+            case ' ':
+                event.preventDefault();
+                if (!this.isYearDisabled(nextYear, this.parsedMin(), this.parsedMax())) {
+                    this.selectYear(nextYear);
+                }
+                return;
+            case 'Escape':
+                event.preventDefault();
+                this.currentView.set('months');
+                queueMicrotask(() => this.focusMonthButton(this.focusedMonth()));
+                return;
+            default:
+                return;
         }
+        event.preventDefault();
+        if (nextYear < pageStart) {
+            this.yearPageStart.update((s) => s - 12);
+        }
+        else if (nextYear >= pageStart + 12) {
+            this.yearPageStart.update((s) => s + 12);
+        }
+        this.focusedYear.set(nextYear);
+        queueMicrotask(() => this.focusYearButton(nextYear));
     }
     onDocumentClick(event) {
         const target = event.target;
@@ -3778,24 +4714,204 @@ class AfDatepickerComponent {
             this.close(false);
         }
     }
-    open() {
-        if (this.disabled() || this.isOpen())
+    // ── ControlValueAccessor ─────────────────────────────────────
+    writeValue(value) {
+        if (this.mode() === 'range') {
+            this.writeRangeValue(value);
+        }
+        else {
+            this.writeSingleValue(value);
+        }
+    }
+    registerOnChange(fn) {
+        this.onChange = fn;
+    }
+    registerOnTouched(fn) {
+        this.onTouched = fn;
+    }
+    setDisabledState(isDisabled) {
+        this.disabled.set(isDisabled);
+    }
+    // ── Validator ────────────────────────────────────────────────
+    validate(control) {
+        const value = control.value;
+        if (this.mode() === 'range') {
+            return this.validateRange(value);
+        }
+        return this.validateSingle(value);
+    }
+    registerOnValidatorChange(fn) {
+        this.onValidatorChange = fn;
+    }
+    // ── Private: Value Handling ──────────────────────────────────
+    writeSingleValue(value) {
+        const date = this.coerceToDate(value);
+        this.selectedDate.set(date);
+        if (date) {
+            this.currentMonth.set(date.getMonth());
+            this.currentYear.set(date.getFullYear());
+            this.focusedDate.set(date);
+        }
+        else {
+            this.focusedDate.set(null);
+        }
+    }
+    writeRangeValue(value) {
+        if (!value || typeof value !== 'object') {
+            this.rangeStart.set(null);
+            this.rangeEnd.set(null);
+            this.rangeSelecting.set(false);
             return;
-        const selected = this.selectedDate();
-        const focusDate = selected || new Date();
-        this.currentMonth.set(focusDate.getMonth());
-        this.currentYear.set(focusDate.getFullYear());
-        this.focusedDate.set(focusDate);
-        this.isOpen.set(true);
-        queueMicrotask(() => this.focusDayButton(focusDate));
+        }
+        const range = value;
+        this.rangeStart.set(this.coerceToDate(range['start']));
+        this.rangeEnd.set(this.coerceToDate(range['end']));
+        this.rangeSelecting.set(false);
+        const focus = this.rangeStart() ?? this.rangeEnd();
+        if (focus) {
+            this.currentMonth.set(focus.getMonth());
+            this.currentYear.set(focus.getFullYear());
+        }
     }
-    close(returnFocus = false) {
-        this.isOpen.set(false);
-        this.onTouched();
-        if (returnFocus) {
-            this.inputRef()?.nativeElement.focus();
+    emitSingleValue(date) {
+        if (this.valueFormat() === 'iso') {
+            this.onChange(date ? this.toIsoString(date) : null);
+        }
+        else {
+            this.onChange(date);
+        }
+        this.onValidatorChange();
+    }
+    emitRangeValue(start, end) {
+        if (this.valueFormat() === 'iso') {
+            this.onChange({
+                start: start ? this.toIsoString(start) : null,
+                end: end ? this.toIsoString(end) : null,
+            });
+        }
+        else {
+            this.onChange({ start, end });
+        }
+        this.onValidatorChange();
+    }
+    // ── Private: Validation ──────────────────────────────────────
+    validateSingle(value) {
+        if (!value)
+            return null;
+        const date = this.coerceToDate(value);
+        if (!date)
+            return null;
+        const min = this.parsedMin();
+        const max = this.parsedMax();
+        if (min && this.compareDays(date, min) < 0) {
+            return { afDatepickerMin: { min, actual: date } };
+        }
+        if (max && this.compareDays(date, max) > 0) {
+            return { afDatepickerMax: { max, actual: date } };
+        }
+        if (this.isDateUnavailable(date)) {
+            return { afDatepickerFilter: true };
+        }
+        return null;
+    }
+    validateRange(value) {
+        if (!value || typeof value !== 'object')
+            return null;
+        const range = value;
+        const start = this.coerceToDate(range['start']);
+        const end = this.coerceToDate(range['end']);
+        const errors = {};
+        const min = this.parsedMin();
+        const max = this.parsedMax();
+        if (start && min && this.compareDays(start, min) < 0) {
+            errors['afDatepickerMin'] = { min, actual: start };
+        }
+        if (end && max && this.compareDays(end, max) > 0) {
+            errors['afDatepickerMax'] = { max, actual: end };
+        }
+        if (start && end && this.compareDays(start, end) > 0) {
+            errors['afDatepickerRange'] = { start, end };
+        }
+        return Object.keys(errors).length > 0 ? errors : null;
+    }
+    // ── Private: Calendar Building ───────────────────────────────
+    buildDay(date, isCurrentMonth, today, selected, rangeStart, rangeEnd) {
+        const isToday = this.isSameDay(date, today);
+        const isSelected = this.mode() === 'single' && selected !== null ? this.isSameDay(date, selected) : false;
+        const isDisabled = this.isDateDisabled(date);
+        const isUnavailable = this.isDateUnavailable(date);
+        let isInRange = false;
+        let isRangeStart = false;
+        let isRangeEnd = false;
+        if (this.mode() === 'range' && rangeStart) {
+            isRangeStart = this.isSameDay(date, rangeStart);
+            if (rangeEnd) {
+                const [lo, hi] = this.compareDays(rangeStart, rangeEnd) <= 0
+                    ? [rangeStart, rangeEnd]
+                    : [rangeEnd, rangeStart];
+                isRangeStart = this.isSameDay(date, lo);
+                isRangeEnd = this.isSameDay(date, hi);
+                isInRange =
+                    !isRangeStart &&
+                        !isRangeEnd &&
+                        this.compareDays(date, lo) > 0 &&
+                        this.compareDays(date, hi) < 0;
+            }
         }
+        return {
+            date,
+            isCurrentMonth,
+            isToday,
+            isSelected,
+            isDisabled,
+            isUnavailable,
+            isInRange,
+            isRangeStart,
+            isRangeEnd,
+        };
+    }
+    // ── Private: Disability Checks ───────────────────────────────
+    /** Checks whether a date falls outside min/max bounds */
+    isDateDisabled(date) {
+        const min = this.parsedMin();
+        const max = this.parsedMax();
+        if (min && this.compareDays(date, min) < 0)
+            return true;
+        if (max && this.compareDays(date, max) > 0)
+            return true;
+        return false;
+    }
+    /** Checks whether a date is explicitly unavailable (disabledDates or dateFilter) */
+    isDateUnavailable(date) {
+        const disabled = this.disabledDates();
+        if (disabled.some((d) => this.isSameDay(d, date)))
+            return true;
+        const filter = this.dateFilter();
+        if (filter && !filter(date))
+            return true;
+        return false;
+    }
+    isMonthDisabled(year, month, min, max) {
+        if (min) {
+            const minMonth = new Date(min.getFullYear(), min.getMonth(), 1);
+            if (new Date(year, month + 1, 0) < minMonth)
+                return true;
+        }
+        if (max) {
+            const maxMonth = new Date(max.getFullYear(), max.getMonth() + 1, 0);
+            if (new Date(year, month, 1) > maxMonth)
+                return true;
+        }
+        return false;
     }
+    isYearDisabled(year, min, max) {
+        if (min && year < min.getFullYear())
+            return true;
+        if (max && year > max.getFullYear())
+            return true;
+        return false;
+    }
+    // ── Private: Focus Management ────────────────────────────────
     setFocusedDate(date) {
         this.currentMonth.set(date.getMonth());
         this.currentYear.set(date.getFullYear());
@@ -3810,6 +4926,41 @@ class AfDatepickerComponent {
         const button = popover.querySelector(`.ct-datepicker__day[data-date="${key}"]`);
         button?.focus();
     }
+    focusMonthButton(monthIndex) {
+        const popover = this.popoverRef()?.nativeElement;
+        if (!popover)
+            return;
+        const buttons = popover.querySelectorAll('.ct-datepicker__month');
+        buttons[monthIndex]?.focus();
+    }
+    focusYearButton(year) {
+        const popover = this.popoverRef()?.nativeElement;
+        if (!popover)
+            return;
+        const buttons = popover.querySelectorAll('.ct-datepicker__year');
+        const pageStart = this.yearPageStart();
+        const index = year - pageStart;
+        if (index >= 0 && index < buttons.length) {
+            buttons[index]?.focus();
+        }
+    }
+    /** Finds the next non-disabled date in the given direction */
+    findNextEnabledDate(from, step) {
+        let next = this.addDays(from, step);
+        let attempts = 0;
+        const singleStep = step > 0 ? 1 : -1;
+        while (this.isDateDisabled(next) && attempts < 365) {
+            next = this.addDays(next, singleStep);
+            attempts++;
+        }
+        return next;
+    }
+    // ── Private: Date Arithmetic ─────────────────────────────────
+    shiftMonth(delta) {
+        const base = this.focusedDate() ?? new Date(this.currentYear(), this.currentMonth(), 1);
+        const next = this.addMonths(base, delta);
+        this.setFocusedDate(next);
+    }
     addDays(date, delta) {
         const next = new Date(date);
         next.setDate(date.getDate() + delta);
@@ -3820,135 +4971,255 @@ class AfDatepickerComponent {
         next.setMonth(date.getMonth() + delta);
         return next;
     }
+    addYears(date, delta) {
+        const next = new Date(date);
+        next.setFullYear(date.getFullYear() + delta);
+        return next;
+    }
     getWeekdayIndex(date) {
         const day = date.getDay();
         return day === 0 ? 6 : day - 1;
     }
-    shiftMonth(delta) {
-        const base = this.focusedDate() || new Date(this.currentYear(), this.currentMonth(), 1);
-        const next = this.addMonths(base, delta);
-        this.setFocusedDate(next);
+    // ── Private: Date Comparison & Parsing ───────────────────────
+    isSameDay(a, b) {
+        return (a.getFullYear() === b.getFullYear() &&
+            a.getMonth() === b.getMonth() &&
+            a.getDate() === b.getDate());
+    }
+    compareDays(a, b) {
+        const da = new Date(a.getFullYear(), a.getMonth(), a.getDate()).getTime();
+        const db = new Date(b.getFullYear(), b.getMonth(), b.getDate()).getTime();
+        return da - db;
     }
-    isSameDay(date1, date2) {
-        return (date1.getFullYear() === date2.getFullYear() &&
-            date1.getMonth() === date2.getMonth() &&
-            date1.getDate() === date2.getDate());
+    parseDate(value) {
+        if (!value)
+            return null;
+        if (value instanceof Date)
+            return value;
+        if (typeof value === 'string') {
+            const parsed = new Date(value);
+            return isNaN(parsed.getTime()) ? null : parsed;
+        }
+        return null;
+    }
+    coerceToDate(value) {
+        if (!value)
+            return null;
+        if (value instanceof Date)
+            return value;
+        if (typeof value === 'string') {
+            const parsed = new Date(value);
+            return isNaN(parsed.getTime()) ? null : parsed;
+        }
+        return null;
+    }
+    toIsoString(date) {
+        return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
     }
     formatDate(date) {
         const tokens = {
             yyyy: String(date.getFullYear()),
-            MMM: this.monthNames[date.getMonth()].substring(0, 3),
+            MMM: MONTH_SHORT[date.getMonth()],
             MM: String(date.getMonth() + 1).padStart(2, '0'),
             dd: String(date.getDate()).padStart(2, '0'),
-            d: String(date.getDate())
+            d: String(date.getDate()),
         };
-        return this.dateFormat().replace(/yyyy|MMM|MM|dd|d/g, token => tokens[token] ?? token);
-    }
-    // ControlValueAccessor implementation
-    writeValue(value) {
-        if (value) {
-            this.selectedDate.set(value);
-            this.currentMonth.set(value.getMonth());
-            this.currentYear.set(value.getFullYear());
-            this.focusedDate.set(value);
-        }
-        else {
-            this.selectedDate.set(null);
-            this.focusedDate.set(null);
-        }
-    }
-    registerOnChange(fn) {
-        this.onChange = fn;
-    }
-    registerOnTouched(fn) {
-        this.onTouched = fn;
-    }
-    setDisabledState(isDisabled) {
-        this.disabled.set(isDisabled);
+        return this.dateFormat().replace(/yyyy|MMM|MM|dd|d/g, (token) => tokens[token] ?? token);
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.2", ngImport: i0, type: AfDatepickerComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.1.2", type: AfDatepickerComponent, isStandalone: true, selector: "af-datepicker", inputs: { label: { classPropertyName: "label", publicName: "label", isSignal: true, isRequired: false, transformFunction: null }, placeholder: { classPropertyName: "placeholder", publicName: "placeholder", isSignal: true, isRequired: false, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "disabled", isSignal: true, isRequired: false, transformFunction: null }, dateFormat: { classPropertyName: "dateFormat", publicName: "dateFormat", isSignal: true, isRequired: false, transformFunction: null }, inputId: { classPropertyName: "inputId", publicName: "inputId", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { disabled: "disabledChange", dateChange: "dateChange" }, host: { listeners: { "document:keydown.escape": "onEscape()", "document:click": "onDocumentClick($event)" } }, providers: [
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.1.2", type: AfDatepickerComponent, isStandalone: true, selector: "af-datepicker", inputs: { label: { classPropertyName: "label", publicName: "label", isSignal: true, isRequired: false, transformFunction: null }, placeholder: { classPropertyName: "placeholder", publicName: "placeholder", isSignal: true, isRequired: false, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "disabled", isSignal: true, isRequired: false, transformFunction: null }, dateFormat: { classPropertyName: "dateFormat", publicName: "dateFormat", isSignal: true, isRequired: false, transformFunction: null }, inputId: { classPropertyName: "inputId", publicName: "inputId", isSignal: true, isRequired: false, transformFunction: null }, min: { classPropertyName: "min", publicName: "min", isSignal: true, isRequired: false, transformFunction: null }, max: { classPropertyName: "max", publicName: "max", isSignal: true, isRequired: false, transformFunction: null }, disabledDates: { classPropertyName: "disabledDates", publicName: "disabledDates", isSignal: true, isRequired: false, transformFunction: null }, dateFilter: { classPropertyName: "dateFilter", publicName: "dateFilter", isSignal: true, isRequired: false, transformFunction: null }, hint: { classPropertyName: "hint", publicName: "hint", isSignal: true, isRequired: false, transformFunction: null }, error: { classPropertyName: "error", publicName: "error", isSignal: true, isRequired: false, transformFunction: null }, required: { classPropertyName: "required", publicName: "required", isSignal: true, isRequired: false, transformFunction: null }, mode: { classPropertyName: "mode", publicName: "mode", isSignal: true, isRequired: false, transformFunction: null }, valueFormat: { classPropertyName: "valueFormat", publicName: "valueFormat", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { disabled: "disabledChange", dateChange: "dateChange", rangeChange: "rangeChange" }, host: { listeners: { "document:click": "onDocumentClick($event)" } }, providers: [
             {
                 provide: NG_VALUE_ACCESSOR,
                 useExisting: forwardRef(() => AfDatepickerComponent),
-                multi: true
-            }
-        ], viewQueries: [{ propertyName: "inputRef", first: true, predicate: ["input"], descendants: true, isSignal: true }, { propertyName: "popoverRef", first: true, predicate: ["popover"], descendants: true, isSignal: true }], ngImport: i0, template: `
-    <div class="ct-field">
+                multi: true,
+            },
+            {
+                provide: NG_VALIDATORS,
+                useExisting: forwardRef(() => AfDatepickerComponent),
+                multi: true,
+            },
+        ], viewQueries: [{ propertyName: "inputRef", first: true, predicate: ["inputEl"], descendants: true, isSignal: true }, { propertyName: "popoverRef", first: true, predicate: ["popoverEl"], descendants: true, isSignal: true }], ngImport: i0, template: `
+    <div class="ct-field" [class.ct-field--error]="error()">
       @if (label()) {
-        <label class="ct-field__label" [attr.for]="inputId()">{{ label() }}</label>
+        <label class="ct-field__label" [attr.for]="inputId()">
+          {{ label() }}
+          @if (required()) {
+            <span aria-label="required"> *</span>
+          }
+        </label>
       }
 
       <div class="ct-datepicker" [attr.data-state]="isOpen() ? 'open' : 'closed'">
-        <input
-          #input
-          class="ct-input"
-          type="text"
-          [id]="inputId()"
-          [placeholder]="placeholder()"
-          [value]="formattedDate()"
-          [disabled]="disabled()"
-          [attr.aria-haspopup]="'dialog'"
-          [attr.aria-expanded]="isOpen()"
-          [attr.aria-controls]="popoverId()"
-          [attr.aria-label]="label() ? null : (placeholder() || 'Select date')"
-          (click)="toggle()"
-          (keydown)="onInputKeydown($event)"
-          (blur)="onTouched()"
-          readonly
-        />
+        <div class="ct-datepicker__input-wrap">
+          <input
+            #inputEl
+            class="ct-input"
+            type="text"
+            [id]="inputId()"
+            [placeholder]="placeholder()"
+            [value]="formattedValue()"
+            [disabled]="disabled()"
+            [required]="required()"
+            [attr.aria-haspopup]="'dialog'"
+            [attr.aria-expanded]="isOpen()"
+            [attr.aria-controls]="popoverId()"
+            [attr.aria-invalid]="error() ? true : null"
+            [attr.aria-describedby]="ariaDescribedBy()"
+            [attr.aria-label]="label() ? null : (placeholder() || 'Select date')"
+            (click)="toggle()"
+            (keydown)="onInputKeydown($event)"
+            (blur)="onTouched()"
+            readonly
+          />
+          @if (hasClearableValue() && !disabled()) {
+            <button
+              class="ct-datepicker__clear"
+              type="button"
+              aria-label="Clear date"
+              (click)="clearValue($event)">
+              <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24"
+                fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"
+                stroke-linejoin="round" aria-hidden="true">
+                <line x1="18" y1="6" x2="6" y2="18"></line>
+                <line x1="6" y1="6" x2="18" y2="18"></line>
+              </svg>
+            </button>
+          }
+        </div>
 
-        @if (isOpen()) {
-          <div
-            #popover
-            class="ct-datepicker__popover"
-            role="dialog"
-            [id]="popoverId()"
-            aria-label="Choose date">
-            <div class="ct-datepicker__header">
-              <button
-                class="ct-button ct-button--ghost ct-button--icon"
-                aria-label="Previous month"
-                type="button"
-                (click)="previousMonth()">
-                &#8249;
-              </button>
-              <div class="ct-datepicker__title">
-                {{ monthNames[currentMonth()] }} {{ currentYear() }}
-              </div>
-              <button
-                class="ct-button ct-button--ghost ct-button--icon"
-                aria-label="Next month"
-                type="button"
-                (click)="nextMonth()">
-                &#8250;
-              </button>
-            </div>
+        <div
+          #popoverEl
+          class="ct-datepicker__popover"
+          role="dialog"
+          [id]="popoverId()"
+          [attr.aria-label]="dialogAriaLabel()"
+          [attr.aria-hidden]="!isOpen() || null">
+
+          <div class="ct-datepicker__header">
+            <button
+              class="ct-button ct-button--ghost ct-button--icon"
+              type="button"
+              [attr.aria-label]="prevButtonAriaLabel()"
+              (click)="navigatePrevious()">
+              &#8249;
+            </button>
+            <button
+              class="ct-datepicker__title"
+              type="button"
+              [attr.aria-label]="titleAriaLabel()"
+              (click)="drillUp()">
+              {{ headerTitle() }}
+            </button>
+            <button
+              class="ct-button ct-button--ghost ct-button--icon"
+              type="button"
+              [attr.aria-label]="nextButtonAriaLabel()"
+              (click)="navigateNext()">
+              &#8250;
+            </button>
+          </div>
 
-            <div class="ct-datepicker__grid" (keydown)="onGridKeydown($event)">
-              @for (day of weekdayLabels; track $index) {
-                <div class="ct-datepicker__weekday">{{ day }}</div>
-              }
-              @for (day of calendarDays(); track day.date.getTime()) {
+          @switch (currentView()) {
+            @case ('days') {
+              <div
+                class="ct-datepicker__grid"
+                role="grid"
+                [attr.aria-label]="gridAriaLabel()"
+                (keydown)="onDayGridKeydown($event)">
+                <div class="ct-datepicker__row" role="row">
+                  @for (day of weekdayLabels; track $index) {
+                    <div class="ct-datepicker__weekday" role="columnheader" [attr.aria-label]="weekdayFullLabels[$index]">
+                      {{ day }}
+                    </div>
+                  }
+                </div>
+                @for (day of calendarDays(); track day.date.getTime()) {
+                  <button
+                    class="ct-datepicker__day"
+                    [attr.data-date]="getDateKey(day.date)"
+                    [attr.data-outside]="!day.isCurrentMonth || null"
+                    [attr.data-today]="day.isToday || null"
+                    [attr.data-unavailable]="day.isUnavailable || null"
+                    [attr.data-highlighted]="isDayHighlighted(day) || null"
+                    [attr.data-in-range]="day.isInRange || null"
+                    [attr.data-range-start]="day.isRangeStart || null"
+                    [attr.data-range-end]="day.isRangeEnd || null"
+                    [attr.aria-selected]="day.isSelected ? 'true' : null"
+                    [attr.aria-current]="day.isToday ? 'date' : null"
+                    [attr.aria-disabled]="day.isDisabled || day.isUnavailable ? 'true' : null"
+                    [disabled]="day.isDisabled || day.isUnavailable"
+                    [attr.tabindex]="getDayTabIndex(day)"
+                    role="gridcell"
+                    type="button"
+                    (click)="onDayClick(day)">
+                    {{ day.date.getDate() }}
+                  </button>
+                }
+              </div>
+              <div class="ct-datepicker__footer">
                 <button
-                  class="ct-datepicker__day"
-                  [attr.data-date]="getDateKey(day.date)"
-                  [attr.data-outside]="!day.isCurrentMonth"
-                  [attr.data-today]="day.isToday"
-                  [attr.aria-selected]="day.isSelected ? 'true' : null"
-                  [attr.aria-current]="day.isToday ? 'date' : null"
-                  [attr.tabindex]="getDayTabIndex(day)"
+                  class="ct-datepicker__today"
                   type="button"
-                  (click)="selectDate(day.date)">
-                  {{ day.date.getDate() }}
+                  [disabled]="isTodayDisabled()"
+                  (click)="goToToday()">
+                  Today
                 </button>
-              }
-            </div>
-          </div>
-        }
+              </div>
+            }
+            @case ('months') {
+              <div
+                class="ct-datepicker__month-grid"
+                role="grid"
+                aria-label="Select month"
+                (keydown)="onMonthGridKeydown($event)">
+                @for (m of monthItems(); track m.index) {
+                  <button
+                    class="ct-datepicker__month"
+                    [attr.aria-selected]="m.isSelected ? 'true' : null"
+                    [attr.data-highlighted]="isMonthHighlighted(m.index) || null"
+                    [disabled]="m.isDisabled"
+                    [attr.tabindex]="getMonthTabIndex(m.index)"
+                    role="gridcell"
+                    type="button"
+                    (click)="selectMonth(m.index)">
+                    {{ m.shortLabel }}
+                  </button>
+                }
+              </div>
+            }
+            @case ('years') {
+              <div
+                class="ct-datepicker__year-grid"
+                role="grid"
+                aria-label="Select year"
+                (keydown)="onYearGridKeydown($event)">
+                @for (y of yearItems(); track y.value) {
+                  <button
+                    class="ct-datepicker__year"
+                    [attr.aria-selected]="y.isSelected ? 'true' : null"
+                    [attr.data-highlighted]="isYearHighlighted(y.value) || null"
+                    [disabled]="y.isDisabled"
+                    [attr.tabindex]="getYearTabIndex(y.value)"
+                    role="gridcell"
+                    type="button"
+                    (click)="selectYear(y.value)">
+                    {{ y.value }}
+                  </button>
+                }
+              </div>
+            }
+          }
+        </div>
       </div>
+
+      @if (hint() && !error()) {
+        <div class="ct-field__hint" [id]="hintId()">{{ hint() }}</div>
+      }
+      @if (error()) {
+        <div class="ct-field__error" [id]="errorId()">{{ error() }}</div>
+      }
     </div>
-  `, isInline: true, styles: [":host{display:block}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+  `, isInline: true, styles: [":host{display:block}.ct-datepicker__input-wrap{position:relative;display:flex;align-items:center}.ct-datepicker__input-wrap .ct-input{width:100%;padding-inline-end:2.25rem}.ct-datepicker__clear{position:absolute;inset-inline-end:.5rem;display:inline-flex;align-items:center;justify-content:center;border:none;background:transparent;cursor:pointer;color:var(--color-text-muted);padding:.25rem;border-radius:var(--radius-sm)}.ct-datepicker__clear:hover{color:var(--color-text-primary)}.ct-datepicker__clear:focus-visible{outline:var(--border-medium) solid var(--color-focus-ring);outline-offset:2px}.ct-datepicker__footer{display:flex;justify-content:center}.ct-datepicker__today{appearance:none;border:none;background:transparent;color:var(--color-brand-primary);cursor:pointer;font-size:var(--font-size-sm);padding:var(--space-1) var(--space-3);border-radius:var(--radius-sm);font-weight:var(--font-weight-medium, 500)}.ct-datepicker__today:hover:not(:disabled){background:var(--color-bg-muted)}.ct-datepicker__today:focus-visible{outline:var(--border-medium) solid var(--color-focus-ring);outline-offset:2px}.ct-datepicker__today:disabled{opacity:var(--opacity-disabled, .5);cursor:not-allowed}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImport: i0, type: AfDatepickerComponent, decorators: [{
             type: Component,
@@ -3956,88 +5227,198 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImpor
                         {
                             provide: NG_VALUE_ACCESSOR,
                             useExisting: forwardRef(() => AfDatepickerComponent),
-                            multi: true
-                        }
+                            multi: true,
+                        },
+                        {
+                            provide: NG_VALIDATORS,
+                            useExisting: forwardRef(() => AfDatepickerComponent),
+                            multi: true,
+                        },
                     ], host: {
-                        '(document:keydown.escape)': 'onEscape()',
                         '(document:click)': 'onDocumentClick($event)',
                     }, template: `
-    <div class="ct-field">
+    <div class="ct-field" [class.ct-field--error]="error()">
       @if (label()) {
-        <label class="ct-field__label" [attr.for]="inputId()">{{ label() }}</label>
+        <label class="ct-field__label" [attr.for]="inputId()">
+          {{ label() }}
+          @if (required()) {
+            <span aria-label="required"> *</span>
+          }
+        </label>
       }
 
       <div class="ct-datepicker" [attr.data-state]="isOpen() ? 'open' : 'closed'">
-        <input
-          #input
-          class="ct-input"
-          type="text"
-          [id]="inputId()"
-          [placeholder]="placeholder()"
-          [value]="formattedDate()"
-          [disabled]="disabled()"
-          [attr.aria-haspopup]="'dialog'"
-          [attr.aria-expanded]="isOpen()"
-          [attr.aria-controls]="popoverId()"
-          [attr.aria-label]="label() ? null : (placeholder() || 'Select date')"
-          (click)="toggle()"
-          (keydown)="onInputKeydown($event)"
-          (blur)="onTouched()"
-          readonly
-        />
+        <div class="ct-datepicker__input-wrap">
+          <input
+            #inputEl
+            class="ct-input"
+            type="text"
+            [id]="inputId()"
+            [placeholder]="placeholder()"
+            [value]="formattedValue()"
+            [disabled]="disabled()"
+            [required]="required()"
+            [attr.aria-haspopup]="'dialog'"
+            [attr.aria-expanded]="isOpen()"
+            [attr.aria-controls]="popoverId()"
+            [attr.aria-invalid]="error() ? true : null"
+            [attr.aria-describedby]="ariaDescribedBy()"
+            [attr.aria-label]="label() ? null : (placeholder() || 'Select date')"
+            (click)="toggle()"
+            (keydown)="onInputKeydown($event)"
+            (blur)="onTouched()"
+            readonly
+          />
+          @if (hasClearableValue() && !disabled()) {
+            <button
+              class="ct-datepicker__clear"
+              type="button"
+              aria-label="Clear date"
+              (click)="clearValue($event)">
+              <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24"
+                fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"
+                stroke-linejoin="round" aria-hidden="true">
+                <line x1="18" y1="6" x2="6" y2="18"></line>
+                <line x1="6" y1="6" x2="18" y2="18"></line>
+              </svg>
+            </button>
+          }
+        </div>
 
-        @if (isOpen()) {
-          <div
-            #popover
-            class="ct-datepicker__popover"
-            role="dialog"
-            [id]="popoverId()"
-            aria-label="Choose date">
-            <div class="ct-datepicker__header">
-              <button
-                class="ct-button ct-button--ghost ct-button--icon"
-                aria-label="Previous month"
-                type="button"
-                (click)="previousMonth()">
-                &#8249;
-              </button>
-              <div class="ct-datepicker__title">
-                {{ monthNames[currentMonth()] }} {{ currentYear() }}
-              </div>
-              <button
-                class="ct-button ct-button--ghost ct-button--icon"
-                aria-label="Next month"
-                type="button"
-                (click)="nextMonth()">
-                &#8250;
-              </button>
-            </div>
+        <div
+          #popoverEl
+          class="ct-datepicker__popover"
+          role="dialog"
+          [id]="popoverId()"
+          [attr.aria-label]="dialogAriaLabel()"
+          [attr.aria-hidden]="!isOpen() || null">
+
+          <div class="ct-datepicker__header">
+            <button
+              class="ct-button ct-button--ghost ct-button--icon"
+              type="button"
+              [attr.aria-label]="prevButtonAriaLabel()"
+              (click)="navigatePrevious()">
+              &#8249;
+            </button>
+            <button
+              class="ct-datepicker__title"
+              type="button"
+              [attr.aria-label]="titleAriaLabel()"
+              (click)="drillUp()">
+              {{ headerTitle() }}
+            </button>
+            <button
+              class="ct-button ct-button--ghost ct-button--icon"
+              type="button"
+              [attr.aria-label]="nextButtonAriaLabel()"
+              (click)="navigateNext()">
+              &#8250;
+            </button>
+          </div>
 
-            <div class="ct-datepicker__grid" (keydown)="onGridKeydown($event)">
-              @for (day of weekdayLabels; track $index) {
-                <div class="ct-datepicker__weekday">{{ day }}</div>
-              }
-              @for (day of calendarDays(); track day.date.getTime()) {
+          @switch (currentView()) {
+            @case ('days') {
+              <div
+                class="ct-datepicker__grid"
+                role="grid"
+                [attr.aria-label]="gridAriaLabel()"
+                (keydown)="onDayGridKeydown($event)">
+                <div class="ct-datepicker__row" role="row">
+                  @for (day of weekdayLabels; track $index) {
+                    <div class="ct-datepicker__weekday" role="columnheader" [attr.aria-label]="weekdayFullLabels[$index]">
+                      {{ day }}
+                    </div>
+                  }
+                </div>
+                @for (day of calendarDays(); track day.date.getTime()) {
+                  <button
+                    class="ct-datepicker__day"
+                    [attr.data-date]="getDateKey(day.date)"
+                    [attr.data-outside]="!day.isCurrentMonth || null"
+                    [attr.data-today]="day.isToday || null"
+                    [attr.data-unavailable]="day.isUnavailable || null"
+                    [attr.data-highlighted]="isDayHighlighted(day) || null"
+                    [attr.data-in-range]="day.isInRange || null"
+                    [attr.data-range-start]="day.isRangeStart || null"
+                    [attr.data-range-end]="day.isRangeEnd || null"
+                    [attr.aria-selected]="day.isSelected ? 'true' : null"
+                    [attr.aria-current]="day.isToday ? 'date' : null"
+                    [attr.aria-disabled]="day.isDisabled || day.isUnavailable ? 'true' : null"
+                    [disabled]="day.isDisabled || day.isUnavailable"
+                    [attr.tabindex]="getDayTabIndex(day)"
+                    role="gridcell"
+                    type="button"
+                    (click)="onDayClick(day)">
+                    {{ day.date.getDate() }}
+                  </button>
+                }
+              </div>
+              <div class="ct-datepicker__footer">
                 <button
-                  class="ct-datepicker__day"
-                  [attr.data-date]="getDateKey(day.date)"
-                  [attr.data-outside]="!day.isCurrentMonth"
-                  [attr.data-today]="day.isToday"
-                  [attr.aria-selected]="day.isSelected ? 'true' : null"
-                  [attr.aria-current]="day.isToday ? 'date' : null"
-                  [attr.tabindex]="getDayTabIndex(day)"
+                  class="ct-datepicker__today"
                   type="button"
-                  (click)="selectDate(day.date)">
-                  {{ day.date.getDate() }}
+                  [disabled]="isTodayDisabled()"
+                  (click)="goToToday()">
+                  Today
                 </button>
-              }
-            </div>
-          </div>
-        }
+              </div>
+            }
+            @case ('months') {
+              <div
+                class="ct-datepicker__month-grid"
+                role="grid"
+                aria-label="Select month"
+                (keydown)="onMonthGridKeydown($event)">
+                @for (m of monthItems(); track m.index) {
+                  <button
+                    class="ct-datepicker__month"
+                    [attr.aria-selected]="m.isSelected ? 'true' : null"
+                    [attr.data-highlighted]="isMonthHighlighted(m.index) || null"
+                    [disabled]="m.isDisabled"
+                    [attr.tabindex]="getMonthTabIndex(m.index)"
+                    role="gridcell"
+                    type="button"
+                    (click)="selectMonth(m.index)">
+                    {{ m.shortLabel }}
+                  </button>
+                }
+              </div>
+            }
+            @case ('years') {
+              <div
+                class="ct-datepicker__year-grid"
+                role="grid"
+                aria-label="Select year"
+                (keydown)="onYearGridKeydown($event)">
+                @for (y of yearItems(); track y.value) {
+                  <button
+                    class="ct-datepicker__year"
+                    [attr.aria-selected]="y.isSelected ? 'true' : null"
+                    [attr.data-highlighted]="isYearHighlighted(y.value) || null"
+                    [disabled]="y.isDisabled"
+                    [attr.tabindex]="getYearTabIndex(y.value)"
+                    role="gridcell"
+                    type="button"
+                    (click)="selectYear(y.value)">
+                    {{ y.value }}
+                  </button>
+                }
+              </div>
+            }
+          }
+        </div>
       </div>
+
+      @if (hint() && !error()) {
+        <div class="ct-field__hint" [id]="hintId()">{{ hint() }}</div>
+      }
+      @if (error()) {
+        <div class="ct-field__error" [id]="errorId()">{{ error() }}</div>
+      }
     </div>
-  `, styles: [":host{display:block}\n"] }]
-        }], propDecorators: { label: [{ type: i0.Input, args: [{ isSignal: true, alias: "label", required: false }] }], placeholder: [{ type: i0.Input, args: [{ isSignal: true, alias: "placeholder", required: false }] }], disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabled", required: false }] }, { type: i0.Output, args: ["disabledChange"] }], dateFormat: [{ type: i0.Input, args: [{ isSignal: true, alias: "dateFormat", required: false }] }], inputId: [{ type: i0.Input, args: [{ isSignal: true, alias: "inputId", required: false }] }], dateChange: [{ type: i0.Output, args: ["dateChange"] }], inputRef: [{ type: i0.ViewChild, args: ['input', { isSignal: true }] }], popoverRef: [{ type: i0.ViewChild, args: ['popover', { isSignal: true }] }] } });
+  `, styles: [":host{display:block}.ct-datepicker__input-wrap{position:relative;display:flex;align-items:center}.ct-datepicker__input-wrap .ct-input{width:100%;padding-inline-end:2.25rem}.ct-datepicker__clear{position:absolute;inset-inline-end:.5rem;display:inline-flex;align-items:center;justify-content:center;border:none;background:transparent;cursor:pointer;color:var(--color-text-muted);padding:.25rem;border-radius:var(--radius-sm)}.ct-datepicker__clear:hover{color:var(--color-text-primary)}.ct-datepicker__clear:focus-visible{outline:var(--border-medium) solid var(--color-focus-ring);outline-offset:2px}.ct-datepicker__footer{display:flex;justify-content:center}.ct-datepicker__today{appearance:none;border:none;background:transparent;color:var(--color-brand-primary);cursor:pointer;font-size:var(--font-size-sm);padding:var(--space-1) var(--space-3);border-radius:var(--radius-sm);font-weight:var(--font-weight-medium, 500)}.ct-datepicker__today:hover:not(:disabled){background:var(--color-bg-muted)}.ct-datepicker__today:focus-visible{outline:var(--border-medium) solid var(--color-focus-ring);outline-offset:2px}.ct-datepicker__today:disabled{opacity:var(--opacity-disabled, .5);cursor:not-allowed}\n"] }]
+        }], propDecorators: { label: [{ type: i0.Input, args: [{ isSignal: true, alias: "label", required: false }] }], placeholder: [{ type: i0.Input, args: [{ isSignal: true, alias: "placeholder", required: false }] }], disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabled", required: false }] }, { type: i0.Output, args: ["disabledChange"] }], dateFormat: [{ type: i0.Input, args: [{ isSignal: true, alias: "dateFormat", required: false }] }], inputId: [{ type: i0.Input, args: [{ isSignal: true, alias: "inputId", required: false }] }], min: [{ type: i0.Input, args: [{ isSignal: true, alias: "min", required: false }] }], max: [{ type: i0.Input, args: [{ isSignal: true, alias: "max", required: false }] }], disabledDates: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabledDates", required: false }] }], dateFilter: [{ type: i0.Input, args: [{ isSignal: true, alias: "dateFilter", required: false }] }], hint: [{ type: i0.Input, args: [{ isSignal: true, alias: "hint", required: false }] }], error: [{ type: i0.Input, args: [{ isSignal: true, alias: "error", required: false }] }], required: [{ type: i0.Input, args: [{ isSignal: true, alias: "required", required: false }] }], mode: [{ type: i0.Input, args: [{ isSignal: true, alias: "mode", required: false }] }], valueFormat: [{ type: i0.Input, args: [{ isSignal: true, alias: "valueFormat", required: false }] }], dateChange: [{ type: i0.Output, args: ["dateChange"] }], rangeChange: [{ type: i0.Output, args: ["rangeChange"] }], inputRef: [{ type: i0.ViewChild, args: ['inputEl', { isSignal: true }] }], popoverRef: [{ type: i0.ViewChild, args: ['popoverEl', { isSignal: true }] }] } });
 
 /**
  * Chip component for labels, tags, statuses, and interactive filters.
@@ -4648,21 +6029,45 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImpor
         }], ctorParameters: () => [], propDecorators: { text: [{ type: i0.Input, args: [{ isSignal: true, alias: "afTooltip", required: false }] }], afTooltipPosition: [{ type: i0.Input, args: [{ isSignal: true, alias: "afTooltipPosition", required: false }] }], afTooltipDelay: [{ type: i0.Input, args: [{ isSignal: true, alias: "afTooltipDelay", required: false }] }], afTooltipDisabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "afTooltipDisabled", required: false }] }] } });
 
 /**
- * Badge component for status indicators
+ * Badge component for status indicators, labels, and counts.
  *
- * @example
- * <af-badge variant="success" icon="+">Approved</af-badge>
- * <af-badge variant="danger">Blocked</af-badge>
+ * Wraps the Construct Design System `ct-badge` with semantic color
+ * variants and optional icon or dot indicators.
+ *
+ * @example Basic usage
+ * <af-badge variant="success">Approved</af-badge>
+ *
+ * @example With icon
+ * <af-badge variant="danger" icon="+">Blocked</af-badge>
+ *
+ * @example With dot indicator
+ * <af-badge variant="info" dot>Online</af-badge>
+ *
+ * @example Status badge for screen readers
+ * <af-badge variant="warning" role="status" ariaLabel="Build status: failing">
+ *   Failing
+ * </af-badge>
+ *
+ * @accessibility
+ * - Non-interactive element — no keyboard navigation required.
+ * - Decorative elements (icon, dot) are hidden from screen readers via `aria-hidden`.
+ * - Use `ariaLabel` when the badge has no visible text or when the visual content
+ *   alone does not convey the full meaning.
+ * - Set `role="status"` when the badge reflects a live value that screen readers
+ *   should announce on change.
  */
 class AfBadgeComponent {
+    /** ARIA role, e.g. `"status"` for live status badges. */
+    role = input('', ...(ngDevMode ? [{ debugName: "role" }] : []));
     /** Accessible label, useful when the badge has no visible text. */
     ariaLabel = input('', ...(ngDevMode ? [{ debugName: "ariaLabel" }] : []));
-    /** Color variant. */
+    /** Semantic color variant. */
     variant = input('default', ...(ngDevMode ? [{ debugName: "variant" }] : []));
-    /** Icon character to display */
+    /** Icon character to display before the label. */
     icon = input('', ...(ngDevMode ? [{ debugName: "icon" }] : []));
-    /** Show a dot indicator instead of icon */
-    dot = input(false, ...(ngDevMode ? [{ debugName: "dot" }] : []));
+    /** Show a dot indicator instead of an icon. */
+    dot = input(false, { ...(ngDevMode ? { debugName: "dot" } : {}), transform: booleanAttribute });
+    /** Computed CSS classes combining base class and variant/icon modifiers. */
     badgeClasses = computed(() => {
         const classes = ['ct-badge'];
         if (this.variant() !== 'default') {
@@ -4674,32 +6079,91 @@ class AfBadgeComponent {
         return classes.join(' ');
     }, ...(ngDevMode ? [{ debugName: "badgeClasses" }] : []));
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.2", ngImport: i0, type: AfBadgeComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.1.2", type: AfBadgeComponent, isStandalone: true, selector: "af-badge", inputs: { ariaLabel: { classPropertyName: "ariaLabel", publicName: "ariaLabel", isSignal: true, isRequired: false, transformFunction: null }, variant: { classPropertyName: "variant", publicName: "variant", isSignal: true, isRequired: false, transformFunction: null }, icon: { classPropertyName: "icon", publicName: "icon", isSignal: true, isRequired: false, transformFunction: null }, dot: { classPropertyName: "dot", publicName: "dot", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0, template: `
-    <span [class]="badgeClasses()" [attr.aria-label]="ariaLabel() || null">
-      @if (icon()) {
-        <span class="ct-badge__icon" aria-hidden="true">{{ icon() }}</span>
-      }
-      @if (dot()) {
-        <span class="ct-badge__dot" aria-hidden="true"></span>
-      }
-      <ng-content />
-    </span>
-  `, isInline: true, styles: [":host{display:inline-block}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.1.2", type: AfBadgeComponent, isStandalone: true, selector: "af-badge", inputs: { role: { classPropertyName: "role", publicName: "role", isSignal: true, isRequired: false, transformFunction: null }, ariaLabel: { classPropertyName: "ariaLabel", publicName: "ariaLabel", isSignal: true, isRequired: false, transformFunction: null }, variant: { classPropertyName: "variant", publicName: "variant", isSignal: true, isRequired: false, transformFunction: null }, icon: { classPropertyName: "icon", publicName: "icon", isSignal: true, isRequired: false, transformFunction: null }, dot: { classPropertyName: "dot", publicName: "dot", isSignal: true, isRequired: false, transformFunction: null } }, host: { properties: { "class": "badgeClasses()", "attr.role": "role() || null", "attr.aria-label": "ariaLabel() || null" } }, ngImport: i0, template: `
+    @if (icon()) {
+      <span class="ct-badge__icon" aria-hidden="true">{{ icon() }}</span>
+    }
+    @if (dot()) {
+      <span class="ct-badge__dot" aria-hidden="true"></span>
+    }
+    <ng-content />
+  `, isInline: true, changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImport: i0, type: AfBadgeComponent, decorators: [{
             type: Component,
-            args: [{ selector: 'af-badge', changeDetection: ChangeDetectionStrategy.OnPush, template: `
-    <span [class]="badgeClasses()" [attr.aria-label]="ariaLabel() || null">
-      @if (icon()) {
-        <span class="ct-badge__icon" aria-hidden="true">{{ icon() }}</span>
-      }
-      @if (dot()) {
-        <span class="ct-badge__dot" aria-hidden="true"></span>
-      }
-      <ng-content />
-    </span>
-  `, styles: [":host{display:inline-block}\n"] }]
-        }], propDecorators: { ariaLabel: [{ type: i0.Input, args: [{ isSignal: true, alias: "ariaLabel", required: false }] }], variant: [{ type: i0.Input, args: [{ isSignal: true, alias: "variant", required: false }] }], icon: [{ type: i0.Input, args: [{ isSignal: true, alias: "icon", required: false }] }], dot: [{ type: i0.Input, args: [{ isSignal: true, alias: "dot", required: false }] }] } });
+            args: [{
+                    selector: 'af-badge',
+                    changeDetection: ChangeDetectionStrategy.OnPush,
+                    host: {
+                        '[class]': 'badgeClasses()',
+                        '[attr.role]': 'role() || null',
+                        '[attr.aria-label]': 'ariaLabel() || null',
+                    },
+                    template: `
+    @if (icon()) {
+      <span class="ct-badge__icon" aria-hidden="true">{{ icon() }}</span>
+    }
+    @if (dot()) {
+      <span class="ct-badge__dot" aria-hidden="true"></span>
+    }
+    <ng-content />
+  `,
+                }]
+        }], propDecorators: { role: [{ type: i0.Input, args: [{ isSignal: true, alias: "role", required: false }] }], ariaLabel: [{ type: i0.Input, args: [{ isSignal: true, alias: "ariaLabel", required: false }] }], variant: [{ type: i0.Input, args: [{ isSignal: true, alias: "variant", required: false }] }], icon: [{ type: i0.Input, args: [{ isSignal: true, alias: "icon", required: false }] }], dot: [{ type: i0.Input, args: [{ isSignal: true, alias: "dot", required: false }] }] } });
+
+/**
+ * Test harness for AfBadgeComponent.
+ *
+ * Provides a semantic API for querying badge state in tests,
+ * abstracting DOM details behind readable method names.
+ *
+ * @example
+ * const harness = new AfBadgeHarness(fixture.nativeElement);
+ * expect(harness.getText()).toBe('Approved');
+ * expect(harness.hasClass('ct-badge--success')).toBe(true);
+ */
+class AfBadgeHarness {
+    hostEl;
+    constructor(container) {
+        const el = container.querySelector('af-badge');
+        if (!el) {
+            throw new Error('AfBadgeHarness: af-badge element not found in container.');
+        }
+        this.hostEl = el;
+    }
+    /** Returns the trimmed text content of the badge (projected content only). */
+    getText() {
+        return this.hostEl.textContent?.trim() ?? '';
+    }
+    /** Returns the full `class` attribute string of the host element. */
+    getClasses() {
+        return this.hostEl.className;
+    }
+    /** Returns whether the host element has the given CSS class. */
+    hasClass(className) {
+        return this.hostEl.classList.contains(className);
+    }
+    /** Returns the `aria-label` attribute value, or `null` if absent. */
+    getAriaLabel() {
+        return this.hostEl.getAttribute('aria-label');
+    }
+    /** Returns the `role` attribute value, or `null` if absent. */
+    getRole() {
+        return this.hostEl.getAttribute('role');
+    }
+    /** Returns whether the badge contains an icon element. */
+    hasIcon() {
+        return this.hostEl.querySelector('.ct-badge__icon') !== null;
+    }
+    /** Returns whether the badge contains a dot indicator. */
+    hasDot() {
+        return this.hostEl.querySelector('.ct-badge__dot') !== null;
+    }
+    /** Returns the text content of the icon element, or empty string if absent. */
+    getIconText() {
+        return this.hostEl.querySelector('.ct-badge__icon')?.textContent?.trim() ?? '';
+    }
+}
 
 /**
  * Progress bar for showing completion state
@@ -6366,7 +7830,7 @@ class AfFileUploadComponent {
         {{ liveAnnouncement() }}
       </span>
     </div>
-  `, isInline: true, styles: [":host{display:block}.af-file-upload__sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}\n"], dependencies: [{ kind: "component", type: AfButtonComponent, selector: "af-button", inputs: ["variant", "size", "type", "disabled", "iconOnly", "ariaLabel", "title"], outputs: ["clicked"] }, { kind: "component", type: AfBadgeComponent, selector: "af-badge", inputs: ["ariaLabel", "variant", "icon", "dot"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+  `, isInline: true, styles: [":host{display:block}.af-file-upload__sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}\n"], dependencies: [{ kind: "component", type: AfButtonComponent, selector: "af-button", inputs: ["variant", "size", "type", "disabled", "iconOnly", "ariaLabel", "title"], outputs: ["clicked"] }, { kind: "component", type: AfBadgeComponent, selector: "af-badge", inputs: ["role", "ariaLabel", "variant", "icon", "dot"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImport: i0, type: AfFileUploadComponent, decorators: [{
             type: Component,
@@ -6465,6 +7929,34 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImpor
   `, styles: [":host{display:block}.af-file-upload__sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}\n"] }]
         }], propDecorators: { label: [{ type: i0.Input, args: [{ isSignal: true, alias: "label", required: false }] }], hint: [{ type: i0.Input, args: [{ isSignal: true, alias: "hint", required: false }] }], error: [{ type: i0.Input, args: [{ isSignal: true, alias: "error", required: false }] }], accept: [{ type: i0.Input, args: [{ isSignal: true, alias: "accept", required: false }] }], maxSize: [{ type: i0.Input, args: [{ isSignal: true, alias: "maxSize", required: false }] }], multiple: [{ type: i0.Input, args: [{ isSignal: true, alias: "multiple", required: false }] }], required: [{ type: i0.Input, args: [{ isSignal: true, alias: "required", required: false }] }], disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabled", required: false }] }, { type: i0.Output, args: ["disabledChange"] }], validationErrors: [{ type: i0.Output, args: ["validationErrors"] }], inputId: [{ type: i0.Input, args: [{ isSignal: true, alias: "inputId", required: false }] }] } });
 
+/**
+ * Injection token to override select-menu screen-reader announcements
+ * and the fallback `aria-label`.
+ *
+ * @example
+ * providers: [{
+ *   provide: AF_SELECT_MENU_I18N,
+ *   useValue: {
+ *     selectOption: 'Option auswählen',
+ *     opened: '{count} Optionen verfügbar',
+ *     closed: 'Auswahl geschlossen',
+ *     selected: '{label} ausgewählt',
+ *     deselected: '{label} abgewählt',
+ *     countSelected: '{count} Optionen ausgewählt',
+ *   },
+ * }]
+ */
+const AF_SELECT_MENU_I18N = new InjectionToken('AfSelectMenuI18n', {
+    factory: () => ({
+        selectOption: 'Select option',
+        opened: '{count} options available',
+        closed: 'Selection closed',
+        selected: '{label} selected',
+        deselected: '{label} deselected',
+        countSelected: '{count} options selected',
+    }),
+});
+
 /**
  * Custom dropdown select component with keyboard navigation
  * and full ARIA listbox pattern for single and multi-select.
@@ -6485,9 +7977,22 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImpor
  *   [multiple]="true"
  *   [formControl]="rolesControl">
  * </af-select-menu>
+ *
+ * @accessibility
+ * - Implements the WAI-ARIA Listbox pattern with a combobox trigger.
+ * - Keyboard: ArrowDown/Up to move highlight, Enter/Space to select,
+ *   Escape to close, Home/End to jump, Tab to select-and-close (single) or close (multi).
+ * - Focus stays on the combobox trigger; `aria-activedescendant` tracks the highlighted option.
+ * - Screen-reader announcements via {@link AriaLiveAnnouncer} for open/close/selection changes.
+ * - All user-facing strings are configurable via {@link AF_SELECT_MENU_I18N} for i18n.
+ * - Uses CSS logical properties for RTL layout support.
+ * - `aria-describedby` links to hint or error text; `aria-invalid` is set on error state.
+ * - Disabled options are marked with `aria-disabled` and skipped during keyboard navigation.
  */
 class AfSelectMenuComponent {
     static nextId = 0;
+    i18n = inject(AF_SELECT_MENU_I18N);
+    announcer = inject(AriaLiveAnnouncer);
     /** Label shown above the select */
     label = input('', ...(ngDevMode ? [{ debugName: "label" }] : []));
     /** Placeholder text when nothing is selected */
@@ -6605,6 +8110,8 @@ class AfSelectMenuComponent {
         this.isOpen.set(true);
         this.highlightedIndex.set(this.findSelectedOrFirstIndex());
         this.scrollHighlightedIntoView();
+        const enabledCount = this.options().filter((o) => !o.disabled).length;
+        this.announcer.announce(this.i18n.opened.replace('{count}', String(enabledCount)));
     }
     /** Closes the listbox */
     closeListbox() {
@@ -6612,6 +8119,7 @@ class AfSelectMenuComponent {
             return;
         this.isOpen.set(false);
         this.highlightedIndex.set(-1);
+        this.announcer.announce(this.i18n.closed);
     }
     /** Selects or toggles an option */
     selectOption(option) {
@@ -6621,15 +8129,21 @@ class AfSelectMenuComponent {
         if (this.multiple()) {
             const current = this.value() ?? [];
             const idx = current.findIndex((v) => cmp(v, option.value));
-            const next = idx >= 0
+            const wasSelected = idx >= 0;
+            const next = wasSelected
                 ? [...current.slice(0, idx), ...current.slice(idx + 1)]
                 : [...current, option.value];
             this.value.set(next);
             this.onChange(next);
+            const msg = wasSelected
+                ? this.i18n.deselected.replace('{label}', option.label)
+                : this.i18n.selected.replace('{label}', option.label);
+            this.announcer.announce(`${msg}, ${this.i18n.countSelected.replace('{count}', String(next.length))}`);
         }
         else {
             this.value.set(option.value);
             this.onChange(option.value);
+            this.announcer.announce(this.i18n.selected.replace('{label}', option.label));
             this.closeListbox();
             this.triggerRef()?.nativeElement.focus();
         }
@@ -6821,7 +8335,7 @@ class AfSelectMenuComponent {
           aria-haspopup="listbox"
           [attr.aria-controls]="listboxId"
           [attr.aria-labelledby]="label() ? labelId : null"
-          [attr.aria-label]="label() ? null : 'Select option'"
+          [attr.aria-label]="label() ? null : i18n.selectOption"
           [attr.aria-activedescendant]="activeDescendantId()"
           [attr.aria-invalid]="error() ? true : null"
           [attr.aria-describedby]="getAriaDescribedBy()"
@@ -6928,7 +8442,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImpor
           aria-haspopup="listbox"
           [attr.aria-controls]="listboxId"
           [attr.aria-labelledby]="label() ? labelId : null"
-          [attr.aria-label]="label() ? null : 'Select option'"
+          [attr.aria-label]="label() ? null : i18n.selectOption"
           [attr.aria-activedescendant]="activeDescendantId()"
           [attr.aria-invalid]="error() ? true : null"
           [attr.aria-describedby]="getAriaDescribedBy()"
@@ -7002,6 +8516,141 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImpor
   `, styles: [":host{display:block}\n"] }]
         }], propDecorators: { label: [{ type: i0.Input, args: [{ isSignal: true, alias: "label", required: false }] }], placeholder: [{ type: i0.Input, args: [{ isSignal: true, alias: "placeholder", required: false }] }], options: [{ type: i0.Input, args: [{ isSignal: true, alias: "options", required: false }] }], hint: [{ type: i0.Input, args: [{ isSignal: true, alias: "hint", required: false }] }], error: [{ type: i0.Input, args: [{ isSignal: true, alias: "error", required: false }] }], required: [{ type: i0.Input, args: [{ isSignal: true, alias: "required", required: false }] }], disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabled", required: false }] }, { type: i0.Output, args: ["disabledChange"] }], multiple: [{ type: i0.Input, args: [{ isSignal: true, alias: "multiple", required: false }] }], size: [{ type: i0.Input, args: [{ isSignal: true, alias: "size", required: false }] }], compareWith: [{ type: i0.Input, args: [{ isSignal: true, alias: "compareWith", required: false }] }], componentId: [{ type: i0.Input, args: [{ isSignal: true, alias: "componentId", required: false }] }], triggerRef: [{ type: i0.ViewChild, args: ['triggerEl', { isSignal: true }] }], listboxRef: [{ type: i0.ViewChild, args: ['listboxEl', { isSignal: true }] }], menuRef: [{ type: i0.ViewChild, args: ['menuEl', { isSignal: true }] }] } });
 
+/**
+ * Test harness for AfSelectMenuComponent.
+ *
+ * Provides a semantic API for interacting with the select-menu in tests,
+ * abstracting DOM details behind readable method names.
+ *
+ * @example
+ * const harness = new AfSelectMenuHarness(fixture.nativeElement);
+ * harness.click();
+ * expect(harness.isOpen()).toBe(true);
+ * expect(harness.getOptionCount()).toBe(4);
+ * harness.clickOption(1);
+ * expect(harness.getTriggerText()).toBe('Banana');
+ */
+class AfSelectMenuHarness {
+    hostEl;
+    constructor(container) {
+        const el = container.querySelector('af-select-menu');
+        if (!el) {
+            throw new Error('AfSelectMenuHarness: af-select-menu element not found in container.');
+        }
+        this.hostEl = el;
+    }
+    /** Returns the trigger `<button>` element. */
+    getTriggerElement() {
+        const btn = this.hostEl.querySelector('.ct-select-menu__trigger');
+        if (!btn) {
+            throw new Error('AfSelectMenuHarness: trigger button not found.');
+        }
+        return btn;
+    }
+    /** Returns the trimmed display text of the trigger. */
+    getTriggerText() {
+        const value = this.hostEl.querySelector('.ct-select-menu__value');
+        return value?.textContent?.trim() ?? '';
+    }
+    /** Clicks the trigger button. */
+    click() {
+        this.getTriggerElement().click();
+    }
+    /** Returns whether the trigger is disabled. */
+    isDisabled() {
+        return this.getTriggerElement().disabled;
+    }
+    /** Returns whether the listbox is currently open. */
+    isOpen() {
+        const menu = this.hostEl.querySelector('.ct-select-menu');
+        return menu?.getAttribute('data-state') === 'open';
+    }
+    /** Returns the `aria-expanded` attribute value. */
+    getAriaExpanded() {
+        return this.getTriggerElement().getAttribute('aria-expanded');
+    }
+    /** Returns the `aria-label` attribute value. */
+    getAriaLabel() {
+        return this.getTriggerElement().getAttribute('aria-label');
+    }
+    /** Returns the `aria-labelledby` attribute value. */
+    getAriaLabelledBy() {
+        return this.getTriggerElement().getAttribute('aria-labelledby');
+    }
+    /** Returns the `aria-activedescendant` attribute value. */
+    getAriaActiveDescendant() {
+        return this.getTriggerElement().getAttribute('aria-activedescendant');
+    }
+    /** Returns the `aria-invalid` attribute value. */
+    getAriaInvalid() {
+        return this.getTriggerElement().getAttribute('aria-invalid');
+    }
+    /** Returns the `aria-required` attribute value. */
+    getAriaRequired() {
+        return this.getTriggerElement().getAttribute('aria-required');
+    }
+    /** Returns the `aria-describedby` attribute value. */
+    getAriaDescribedBy() {
+        return this.getTriggerElement().getAttribute('aria-describedby');
+    }
+    /** Returns all option elements inside the listbox. */
+    getOptions() {
+        return Array.from(this.hostEl.querySelectorAll('[role="option"]'));
+    }
+    /** Returns the trimmed text of the option at the given index. */
+    getOptionText(index) {
+        const options = this.getOptions();
+        if (index < 0 || index >= options.length) {
+            throw new Error(`AfSelectMenuHarness: option index ${index} out of bounds (${options.length} options).`);
+        }
+        return options[index].textContent?.trim() ?? '';
+    }
+    /** Returns the number of options. */
+    getOptionCount() {
+        return this.getOptions().length;
+    }
+    /** Returns whether the option at the given index is selected. */
+    isOptionSelected(index) {
+        return this.getOptions()[index]?.getAttribute('aria-selected') === 'true';
+    }
+    /** Returns whether the option at the given index is disabled. */
+    isOptionDisabled(index) {
+        return this.getOptions()[index]?.getAttribute('aria-disabled') === 'true';
+    }
+    /** Returns whether the option at the given index is highlighted. */
+    isOptionHighlighted(index) {
+        return this.getOptions()[index]?.hasAttribute('data-highlighted') ?? false;
+    }
+    /** Clicks the option at the given index. */
+    clickOption(index) {
+        const options = this.getOptions();
+        if (index < 0 || index >= options.length) {
+            throw new Error(`AfSelectMenuHarness: option index ${index} out of bounds (${options.length} options).`);
+        }
+        options[index].click();
+    }
+    /** Returns the trimmed label text, or empty string if no label. */
+    getLabelText() {
+        const label = this.hostEl.querySelector('.ct-field__label');
+        return label?.textContent?.trim() ?? '';
+    }
+    /** Returns the trimmed hint text, or empty string if no hint. */
+    getHintText() {
+        const hint = this.hostEl.querySelector('.ct-field__hint');
+        return hint?.textContent?.trim() ?? '';
+    }
+    /** Returns the trimmed error text, or empty string if no error. */
+    getErrorText() {
+        const error = this.hostEl.querySelector('.ct-field__error');
+        return error?.textContent?.trim() ?? '';
+    }
+    /** Returns whether the select-menu wrapper has the given CSS class. */
+    hasClass(className) {
+        const menu = this.hostEl.querySelector('.ct-select-menu');
+        return menu?.classList.contains(className) ?? false;
+    }
+}
+
 let nextId = 0;
 /**
  * Individual navigation item used within af-navbar or af-toolbar.
@@ -8483,5 +10132,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.2", ngImpor
  * Generated bundle index. Do not edit.
  */
 
-export { AfAccordionComponent, AfAccordionItemComponent, AfAlertComponent, AfAppShellComponent, AfAppShellPageHeaderComponent, AfAppShellV2Component, AfAppShellV2ToolbarComponent, AfAvatarComponent, AfBadgeComponent, AfBannerComponent, AfBreadcrumbsComponent, AfButtonComponent, AfCardComponent, AfCellDefDirective, AfCheckboxComponent, AfChipComponent, AfChipInputComponent, AfComboboxComponent, AfDataTableComponent, AfDatepickerComponent, AfDividerComponent, AfDrawerComponent, AfDropdownComponent, AfEmptyStateComponent, AfFieldComponent, AfFileUploadComponent, AfFormatLabelPipe, AfIconComponent, AfInputComponent, AfModalComponent, AfNavItemComponent, AfNavTabsComponent, AfNavbarComponent, AfPaginationComponent, AfPopoverComponent, AfPopoverTriggerDirective, AfProgressBarComponent, AfRadioComponent, AfRadioGroupComponent, AfSelectComponent, AfSelectMenuComponent, AfSidebarComponent, AfSkeletonComponent, AfSkipLinkComponent, AfSliderComponent, AfSpinnerComponent, AfSwitchComponent, AfTabPanelComponent, AfTableBodyComponent, AfTableCellComponent, AfTableComponent, AfTableHeaderCellComponent, AfTableHeaderComponent, AfTableRowComponent, AfTabsComponent, AfTextareaComponent, AfToastContainerComponent, AfToastService, AfToggleGroupComponent, AfToolbarComponent, AfTooltipDirective };
+export { AF_ACCORDION_I18N, AF_ALERT_I18N, AF_INPUT_I18N, AF_SELECT_MENU_I18N, AfAccordionComponent, AfAccordionHarness, AfAccordionItemComponent, AfAccordionItemHarness, AfAlertComponent, AfAlertHarness, AfAppShellComponent, AfAppShellPageHeaderComponent, AfAppShellV2Component, AfAppShellV2ToolbarComponent, AfAvatarComponent, AfBadgeComponent, AfBadgeHarness, AfBannerComponent, AfBreadcrumbsComponent, AfButtonComponent, AfButtonHarness, AfCardComponent, AfCellDefDirective, AfCheckboxComponent, AfChipComponent, AfChipInputComponent, AfComboboxComponent, AfDataTableComponent, AfDatepickerComponent, AfDividerComponent, AfDrawerComponent, AfDropdownComponent, AfEmptyStateComponent, AfFieldComponent, AfFileUploadComponent, AfFormatLabelPipe, AfIconComponent, AfInputComponent, AfInputHarness, AfModalComponent, AfNavItemComponent, AfNavTabsComponent, AfNavbarComponent, AfPaginationComponent, AfPopoverComponent, AfPopoverTriggerDirective, AfProgressBarComponent, AfRadioComponent, AfRadioGroupComponent, AfSelectComponent, AfSelectMenuComponent, AfSelectMenuHarness, AfSidebarComponent, AfSkeletonComponent, AfSkipLinkComponent, AfSliderComponent, AfSpinnerComponent, AfSwitchComponent, AfTabPanelComponent, AfTableBodyComponent, AfTableCellComponent, AfTableComponent, AfTableHeaderCellComponent, AfTableHeaderComponent, AfTableRowComponent, AfTabsComponent, AfTextareaComponent, AfToastContainerComponent, AfToastService, AfToggleGroupComponent, AfToolbarComponent, AfTooltipDirective };
 //# sourceMappingURL=neuravision-ng-construct.mjs.map