From a2ba418ebc8395051f7a0a0e6af15e7655a1ef25 Mon Sep 17 00:00:00 2001
From: Ly Tempel <ly.tempel@bitweb.ee>
Date: Thu, 6 Aug 2026 10:21:25 +0300
Subject: [PATCH 1/2] fix(search): fix a11y violations in Storybook stories
 #599

---
 skills/tedi-angular/references/forms.md       | 20 +++++++++--
 tedi/components/form/search/search.stories.ts | 34 ++++++++++++++-----
 2 files changed, 43 insertions(+), 11 deletions(-)

diff --git a/skills/tedi-angular/references/forms.md b/skills/tedi-angular/references/forms.md
index 97dd2a07c..d3c58a1ca 100644
--- a/skills/tedi-angular/references/forms.md
+++ b/skills/tedi-angular/references/forms.md
@@ -8,7 +8,8 @@ TEDI form controls implement Angular's `ControlValueAccessor` interface, integra
 |-----------|----------|------------|
 | TextFieldComponent | `input[tedi-text-field]` | `string` |
 | NumberFieldComponent | `tedi-number-field` | `number` |
-| CheckboxComponent | `input[tedi-checkbox]` | `boolean` |
+| SearchComponent | `tedi-search` | `string` |
+| SliderComponent | `tedi-slider` | `number` |
 | CheckboxGroupComponent | `tedi-checkbox-group` | `string[]` |
 | RadioGroupComponent | `tedi-radio-group` | `string \| null` |
 | ToggleComponent | `tedi-toggle` | `boolean` |
@@ -16,9 +17,10 @@ TEDI form controls implement Angular's `ControlValueAccessor` interface, integra
 | DatePickerComponent | `tedi-date-picker` | `Date \| null` — **deprecated**, use `DateFieldComponent` |
 | TimeFieldComponent | `tedi-time-field` | `string \| null` (HH:mm) |
 | TimePickerComponent | `tedi-time-picker` | `string \| null` (HH:mm) |
-| DropdownComponent | `tedi-dropdown` | `string` |
 | SelectComponent | `tedi-select` | `T \| T[]` |
 
+`CheckboxComponent` (`input[type=checkbox][tedi-checkbox]`) is **not** a TEDI value accessor — it styles a native checkbox, so `[formControl]` on it is handled by Angular's built-in `CheckboxControlValueAccessor` and yields a `boolean`. Inside a managed `<tedi-checkbox-group>`, its `value` input is a `string` identity instead. `DropdownComponent` (`tedi-dropdown`) lives in `overlay/` and is not a form control — it exposes `[(value)]` but implements no `ControlValueAccessor`.
+
 ## Basic Usage with Reactive Forms
 
 ```typescript
@@ -56,7 +58,7 @@ import {
         <input tedi-text-field formControlName="email" type="email" />
       </tedi-form-field>
 
-      <input tedi-checkbox formControlName="agree" />
+      <input tedi-checkbox type="checkbox" formControlName="agree" />
     </form>
   `,
 })
@@ -143,6 +145,18 @@ this.control.disable();
 
 The component combines native disabled state with form-disabled state internally.
 
+## Search
+
+`SearchComponent` (`tedi-search`) is a `string` value accessor that renders its own `tedi-form-field` — do not wrap it in one. It requires `inputId`, and takes an optional trailing `button` (`{ text?, icon?, variant?, ariaLabel? }`); `searchEvent` fires on Enter or button click.
+
+```html
+<tedi-search inputId="search" label="Otsing" [formControl]="query" (searchEvent)="run($event)" />
+```
+
+The host is a `role="search"` landmark whose accessible name falls back to `ariaLabel` → `label` → `placeholder` → the translated "search". **When a page renders more than one `tedi-search`, give each a distinct `ariaLabel`** — identically named landmarks of the same type fail axe's `landmark-unique` rule. The visible `<label>` is unaffected; `ariaLabel` names only the landmark.
+
+If you build a suggestion panel around the field, `aria-expanded` / `aria-controls` belong on an element with `role="combobox"` — they are not permitted on a plain textbox (`aria-allowed-attr`). Point `aria-controls` at a `role="listbox"` popup for a list of options, or a `role="dialog"` popup (with `aria-haspopup="dialog"`) when the panel mixes results with other controls. Bind it conditionally — `[attr.aria-controls]="open() ? 'panel-id' : null"` — since a popup rendered with `@if` or a CDK overlay is absent while closed, and a reference to a missing id fails `aria-valid-attr-value`.
+
 ## Date Selection
 
 Use `DateFieldComponent` (`tedi-date-field`) — it is the successor to the now-deprecated `DatePickerComponent`. It wraps a typed text input with a popover (or modal) calendar, and supports `single`, `multiple` and `range` modes.
diff --git a/tedi/components/form/search/search.stories.ts b/tedi/components/form/search/search.stories.ts
index ab1af1d7b..34446476d 100644
--- a/tedi/components/form/search/search.stories.ts
+++ b/tedi/components/form/search/search.stories.ts
@@ -171,7 +171,7 @@ const LIVE_RESULTS_STYLES = `
         type="text"
         role="combobox"
         aria-autocomplete="list"
-        aria-controls="search-combobox-listbox"
+        [attr.aria-controls]="isOpen() ? 'search-combobox-listbox' : null"
         [attr.aria-expanded]="isOpen()"
         [attr.aria-activedescendant]="activeOptionId()"
         [value]="value()"
@@ -319,6 +319,11 @@ class SearchSuggestionsDemoComponent {
  * field (not in an overlay), so focus flows naturally: Tab from the field moves
  * through the action buttons. Opens on focus, closes on Esc or when focus leaves
  * the field and its panel.
+ *
+ * The panel mixes a result with actions, so it is not a listbox: the input is a
+ * `role="combobox"` with `aria-haspopup="dialog"` pointing at a `role="dialog"`
+ * panel. `aria-expanded` / `aria-controls` are only valid on a combobox — on a
+ * plain textbox they fail the `aria-allowed-attr` rule.
  */
 @Component({
   standalone: true,
@@ -345,7 +350,9 @@ class SearchSuggestionsDemoComponent {
           tedi-text-field
           id="search-result"
           type="text"
-          aria-controls="search-result-panel"
+          role="combobox"
+          aria-haspopup="dialog"
+          [attr.aria-controls]="open() ? 'search-result-panel' : null"
           [attr.aria-expanded]="open()"
           [value]="value()"
           (valueChange)="value.set($event)"
@@ -357,7 +364,7 @@ class SearchSuggestionsDemoComponent {
       @if (open()) {
         <div
           id="search-result-panel"
-          role="group"
+          role="dialog"
           aria-label="Otsingutulemus"
           class="tedi-search-demo__results"
         >
@@ -791,17 +798,24 @@ export const Sizes: Story = {
         <div class="tedi-search-sizes__row" *ngFor="let size of SIZES">
           <p tedi-text modifiers="bold" class="tedi-search-sizes__label">{{ size | titlecase }}</p>
           <div class="tedi-search-sizes__fields">
-            <tedi-search [inputId]="'size-' + size + '-plain'" [size]="size" label="Otsing" />
+            <tedi-search
+              [inputId]="'size-' + size + '-plain'"
+              [size]="size"
+              label="Otsing"
+              [ariaLabel]="'Otsing – ' + size + ', ilma nuputa'"
+            />
             <tedi-search
               [inputId]="'size-' + size + '-icon'"
               [size]="size"
               label="Otsing"
+              [ariaLabel]="'Otsing – ' + size + ', nupp ikooniga'"
               [button]="{ ariaLabel: 'Otsi' }"
             />
             <tedi-search
               [inputId]="'size-' + size + '-button'"
               [size]="size"
               label="Otsing"
+              [ariaLabel]="'Otsing – ' + size + ', nupp ikooni ja tekstiga'"
               [button]="{ text: 'Otsi' }"
             />
           </div>
@@ -826,25 +840,29 @@ export const States: Story = {
         <tedi-row *ngFor="let state of PSEUDO_STATE" cols="1" [sm]="{ cols: 6 }" alignItems="center">
           <tedi-col width="1"><p tedi-text modifiers="bold">{{ state }}</p></tedi-col>
           <tedi-col width="1" [sm]="{ width: 5 }">
-            <tedi-search [inputId]="'search-states-' + state" label="Otsing" />
+            <tedi-search
+              [inputId]="'search-states-' + state"
+              label="Otsing"
+              [ariaLabel]="'Otsing – ' + state"
+            />
           </tedi-col>
         </tedi-row>
         <tedi-row cols="1" [sm]="{ cols: 6 }" alignItems="center">
           <tedi-col width="1"><p tedi-text modifiers="bold">Disabled</p></tedi-col>
           <tedi-col width="1" [sm]="{ width: 5 }">
-            <tedi-search inputId="search-states-disabled" label="Otsing" [disabled]="true" />
+            <tedi-search inputId="search-states-disabled" label="Otsing" ariaLabel="Otsing – Disabled" [disabled]="true" />
           </tedi-col>
         </tedi-row>
         <tedi-row cols="1" [sm]="{ cols: 6 }" alignItems="center">
           <tedi-col width="1"><p tedi-text modifiers="bold">Success</p></tedi-col>
           <tedi-col width="1" [sm]="{ width: 5 }">
-            <tedi-search inputId="search-states-success" label="Otsing" [feedbackText]="{ text: 'Tagasiside tekst', type: 'valid' }" />
+            <tedi-search inputId="search-states-success" label="Otsing" ariaLabel="Otsing – Success" [feedbackText]="{ text: 'Tagasiside tekst', type: 'valid' }" />
           </tedi-col>
         </tedi-row>
         <tedi-row cols="1" [sm]="{ cols: 6 }" alignItems="center">
           <tedi-col width="1"><p tedi-text modifiers="bold">Error</p></tedi-col>
           <tedi-col width="1" [sm]="{ width: 5 }">
-            <tedi-search inputId="search-states-error" label="Otsing" [feedbackText]="{ text: 'Tagasiside tekst', type: 'error' }" />
+            <tedi-search inputId="search-states-error" label="Otsing" ariaLabel="Otsing – Error" [feedbackText]="{ text: 'Tagasiside tekst', type: 'error' }" />
           </tedi-col>
         </tedi-row>
       </tedi-row>

From 99075ff75f917f74b079b848bfa07b717dbc8d1d Mon Sep 17 00:00:00 2001
From: Ly Tempel <ly.tempel@bitweb.ee>
Date: Thu, 6 Aug 2026 11:34:03 +0300
Subject: [PATCH 2/2] fix(search): add CR fixes #599

---
 skills/tedi-angular/references/forms.md       |  2 +-
 tedi/components/form/search/search.stories.ts | 58 +++++++++++++++++--
 2 files changed, 53 insertions(+), 7 deletions(-)

diff --git a/skills/tedi-angular/references/forms.md b/skills/tedi-angular/references/forms.md
index d3c58a1ca..f6f617a8a 100644
--- a/skills/tedi-angular/references/forms.md
+++ b/skills/tedi-angular/references/forms.md
@@ -155,7 +155,7 @@ The component combines native disabled state with form-disabled state internally
 
 The host is a `role="search"` landmark whose accessible name falls back to `ariaLabel` → `label` → `placeholder` → the translated "search". **When a page renders more than one `tedi-search`, give each a distinct `ariaLabel`** — identically named landmarks of the same type fail axe's `landmark-unique` rule. The visible `<label>` is unaffected; `ariaLabel` names only the landmark.
 
-If you build a suggestion panel around the field, `aria-expanded` / `aria-controls` belong on an element with `role="combobox"` — they are not permitted on a plain textbox (`aria-allowed-attr`). Point `aria-controls` at a `role="listbox"` popup for a list of options, or a `role="dialog"` popup (with `aria-haspopup="dialog"`) when the panel mixes results with other controls. Bind it conditionally — `[attr.aria-controls]="open() ? 'panel-id' : null"` — since a popup rendered with `@if` or a CDK overlay is absent while closed, and a reference to a missing id fails `aria-valid-attr-value`.
+If you build a suggestion panel around the field, `aria-expanded` is the attribute to watch: it is not permitted on a plain textbox (`aria-allowed-attr`), so the input needs `role="combobox"`. `aria-controls` and `aria-haspopup` are global attributes and are valid on a plain text input either way. Point `aria-controls` at a `role="listbox"` popup for a list of options, or a `role="dialog"` popup (with `aria-haspopup="dialog"`) when the panel mixes results with other controls. Bind it conditionally — `[attr.aria-controls]="open() ? 'panel-id' : null"` — since a popup rendered with `@if` or a CDK overlay is absent while closed, and a reference to a missing id fails `aria-valid-attr-value`.
 
 ## Date Selection
 
diff --git a/tedi/components/form/search/search.stories.ts b/tedi/components/form/search/search.stories.ts
index 34446476d..67651f46a 100644
--- a/tedi/components/form/search/search.stories.ts
+++ b/tedi/components/form/search/search.stories.ts
@@ -1,9 +1,11 @@
 import { TitleCasePipe } from "@angular/common";
 import {
+  afterNextRender,
   Component,
   computed,
   ElementRef,
   inject,
+  Injector,
   OnDestroy,
   signal,
   viewChild,
@@ -317,13 +319,17 @@ class SearchSuggestionsDemoComponent {
  * A single matched result with fallback actions and a hint — e.g. a
  * national-registry person lookup. The result panel renders inline below the
  * field (not in an overlay), so focus flows naturally: Tab from the field moves
- * through the action buttons. Opens on focus, closes on Esc or when focus leaves
- * the field and its panel.
+ * through the action buttons. It opens on focus, and ArrowDown moves focus into
+ * the dialog. Esc closes it from either the field or the dialog, and selecting a
+ * result closes it too — both hand focus back to the input rather than dropping
+ * it when the panel unmounts. It also closes when focus leaves the field and
+ * its panel.
  *
  * The panel mixes a result with actions, so it is not a listbox: the input is a
  * `role="combobox"` with `aria-haspopup="dialog"` pointing at a `role="dialog"`
- * panel. `aria-expanded` / `aria-controls` are only valid on a combobox — on a
- * plain textbox they fail the `aria-allowed-attr` rule.
+ * panel. The combobox role is what makes `aria-expanded` legal — on a plain
+ * textbox it fails the `aria-allowed-attr` rule. `aria-controls` and
+ * `aria-haspopup` are global attributes, so those were valid either way.
  */
 @Component({
   standalone: true,
@@ -347,6 +353,7 @@ class SearchSuggestionsDemoComponent {
       <tedi-form-field>
         <label tedi-label for="search-result">Otsi</label>
         <input
+          #comboboxInput
           tedi-text-field
           id="search-result"
           type="text"
@@ -356,7 +363,8 @@ class SearchSuggestionsDemoComponent {
           [attr.aria-expanded]="open()"
           [value]="value()"
           (valueChange)="value.set($event)"
-          (focus)="open.set(true)"
+          (focus)="onInputFocus()"
+          (keydown.arrowdown)="onArrowDown($event)"
           (keydown.escape)="open.set(false)"
         />
       </tedi-form-field>
@@ -367,11 +375,12 @@ class SearchSuggestionsDemoComponent {
           role="dialog"
           aria-label="Otsingutulemus"
           class="tedi-search-demo__results"
+          (keydown.escape)="closeAndRestoreFocus()"
         >
           <button
             type="button"
             class="tedi-search-demo__result"
-            (click)="open.set(false)"
+            (click)="closeAndRestoreFocus()"
           >
             <tedi-dropdown-item-value>
               <tedi-dropdown-item-value-label
@@ -439,9 +448,46 @@ class SearchSuggestionsDemoComponent {
 })
 class SearchResultActionsDemoComponent {
   private readonly host = inject<ElementRef<HTMLElement>>(ElementRef);
+  private readonly injector = inject(Injector);
+  private readonly input =
+    viewChild.required<ElementRef<HTMLInputElement>>("comboboxInput");
+
+  /** Set while focus is moved back to the input, so it does not reopen the dialog. */
+  private restoringFocus = false;
+
   readonly value = signal("4954080254");
   readonly open = signal(false);
 
+  onInputFocus(): void {
+    if (this.restoringFocus) {
+      this.restoringFocus = false;
+      return;
+    }
+    this.open.set(true);
+  }
+
+  /** ArrowDown moves focus into the dialog, as the combobox pattern expects. */
+  onArrowDown(event: Event): void {
+    event.preventDefault();
+    this.open.set(true);
+
+    // The panel renders on the next change-detection tick.
+    afterNextRender(
+      () =>
+        this.host.nativeElement
+          .querySelector<HTMLElement>(".tedi-search-demo__result")
+          ?.focus(),
+      { injector: this.injector },
+    );
+  }
+
+  /** Closing from inside the dialog must hand focus back to the input. */
+  closeAndRestoreFocus(): void {
+    this.open.set(false);
+    this.restoringFocus = true;
+    this.input().nativeElement.focus();
+  }
+
   onFocusOut(event: FocusEvent): void {
     const next = event.relatedTarget as Node | null;
     if (!next || !this.host.nativeElement.contains(next)) {