chore(demo): DocAPIItem value reflect in URL (#9225)

projects/addon-doc/components/api/api-item.component.ts

@@ -1,12 +1,18 @@
-import {NgForOf, NgIf, NgSwitch, NgSwitchCase} from '@angular/common';
+import {Location, NgForOf, NgIf, NgSwitch, NgSwitchCase} from '@angular/common';
 import {
     ChangeDetectionStrategy,
     Component,
     EventEmitter,
+    inject,
     Input,
+    type OnInit,
     Output,
 } from '@angular/core';
 import {FormsModule} from '@angular/forms';
+import {ActivatedRoute, type Params, UrlSerializer} from '@angular/router';
+import {TUI_DOC_URL_STATE_HANDLER} from '@taiga-ui/addon-doc/tokens';
+import {tuiCoerceValue} from '@taiga-ui/addon-doc/utils';
+import {tuiIsNumber} from '@taiga-ui/cdk/utils/miscellaneous';
 import {TuiIcon} from '@taiga-ui/core/components/icon';
 import {TuiTextfield} from '@taiga-ui/core/components/textfield';
 import {TuiDataListWrapper} from '@taiga-ui/kit/components/data-list-wrapper';
@@ -18,6 +24,8 @@ import {TuiTextfieldControllerModule} from '@taiga-ui/legacy/directives/textfiel
 import {TuiInspectPipe} from '../documentation/pipes/inspect.pipe';
 import {TuiDocTypeReferencePipe} from '../documentation/pipes/type-reference.pipe';
 
+const SERIALIZED_SUFFIX = '$';
+
 @Component({
     standalone: true,
     selector: 'tr[tuiDocAPIItem]',
@@ -41,7 +49,12 @@ import {TuiDocTypeReferencePipe} from '../documentation/pipes/type-reference.pip
     styleUrls: ['./api-item.style.less'],
     changeDetection: ChangeDetectionStrategy.OnPush,
 })
-export class TuiDocAPIItem<T> {
+export class TuiDocAPIItem<T> implements OnInit {
+    private readonly locationRef = inject(Location);
+    private readonly activatedRoute = inject(ActivatedRoute);
+    private readonly urlSerializer = inject(UrlSerializer);
+    private readonly urlStateHandler = inject(TUI_DOC_URL_STATE_HANDLER);
+
     @Input()
     public name = '';
 
@@ -56,4 +69,58 @@ export class TuiDocAPIItem<T> {
 
     @Output()
     public readonly valueChange = new EventEmitter<T>();
+
+    public ngOnInit(): void {
+        this.parseParams(this.activatedRoute.snapshot.queryParams);
+    }
+
+    public onValueChange(value: T): void {
+        this.value = value;
+        this.valueChange.emit(value);
+        this.setQueryParam(value);
+    }
+
+    private clearBrackets(value: string): string {
+        return value.replaceAll(/[()[\]]/g, '');
+    }
+
+    private parseParams(params: Params): void {
+        const name = this.clearBrackets(this.name);
+        const propertyValue: string | undefined = params[name];
+        const propertyValueWithSuffix: number | string | undefined =
+            params[`${name}${SERIALIZED_SUFFIX}`];
+
+        if (!propertyValue && !propertyValueWithSuffix) {
+            return;
+        }
+
+        let value =
+            !!propertyValueWithSuffix && this.items
+                ? this.items[propertyValueWithSuffix as number]
+                : tuiCoerceValue(propertyValue);
+
+        if (this.type === 'string' && tuiIsNumber(value)) {
+            value = value.toString();
+        }
+
+        this.onValueChange(value as T);
+    }
+
+    private setQueryParam(value: T | boolean | number | string | null): void {
+        const tree = this.urlSerializer.parse(this.locationRef.path());
+
+        const isValueAvailableByKey = value instanceof Object;
+        const computedValue =
+            isValueAvailableByKey && this.items ? this.items.indexOf(value as T) : value;
+
+        const suffix = isValueAvailableByKey ? SERIALIZED_SUFFIX : '';
+        const propName = this.clearBrackets(this.name) + suffix;
+
+        tree.queryParams = {
+            ...tree.queryParams,
+            [propName]: computedValue,
+        };
+
+        this.locationRef.go(this.urlStateHandler(tree));
+    }
 }

projects/addon-doc/components/api/api-item.template.html

@@ -44,7 +44,7 @@
             placeholder="null"
             tuiTextfield
             [ngModel]="value ?? null"
-            (ngModelChange)="valueChange.emit($event)"
+            (ngModelChange)="onValueChange($event)"
         ></select>
         <tui-data-list-wrapper
             *tuiTextfieldDropdown
@@ -66,7 +66,7 @@
                 type="checkbox"
                 [id]="name"
                 [ngModel]="value"
-                (ngModelChange)="valueChange.emit($event)"
+                (ngModelChange)="onValueChange($event)"
             />
 
             <tui-textfield
@@ -78,7 +78,7 @@
                     tuiTextfield
                     [id]="name"
                     [ngModel]="value || ''"
-                    (ngModelChange)="valueChange.emit($event)"
+                    (ngModelChange)="onValueChange($event)"
                 />
             </tui-textfield>
 
@@ -90,7 +90,7 @@
                 [ngModel]="value"
                 [step]="1"
                 [tuiTextfieldLabelOutside]="true"
-                (ngModelChange)="valueChange.emit($event || 0)"
+                (ngModelChange)="onValueChange($event || 0)"
             />
         </ng-container>
     </ng-template>

projects/demo-playwright/tests/core/button/button.spec.ts

@@ -5,7 +5,7 @@ test.describe('Button', () => {
     test('darkMode=true + appearance=icon + hovered state', async ({page}) => {
         await tuiGoto(
             page,
-            '/components/button/API?darkMode=true&appearance=icon&icon=tuiIconEyeOff',
+            '/components/button/API?darkMode=true&appearance=icon&[email protected]',
         );
         const {apiPageExample} = new TuiDocumentationPagePO(page);