feat(addon-doc): API add new component (#9015)

Co-authored-by: taiga-family-bot <[email protected]>

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

@@ -0,0 +1,59 @@
+import {NgForOf, NgIf, NgSwitch, NgSwitchCase} from '@angular/common';
+import {
+    ChangeDetectionStrategy,
+    Component,
+    EventEmitter,
+    Input,
+    Output,
+} from '@angular/core';
+import {FormsModule} from '@angular/forms';
+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';
+import {TuiSwitch} from '@taiga-ui/kit/components/switch';
+import {TuiChevron} from '@taiga-ui/kit/directives/chevron';
+import {TuiInputNumberModule} from '@taiga-ui/legacy/components/input-number';
+import {TuiTextfieldControllerModule} from '@taiga-ui/legacy/directives/textfield-controller';
+
+import {TuiInspectPipe} from '../documentation/pipes/inspect.pipe';
+import {TuiDocTypeReferencePipe} from '../documentation/pipes/type-reference.pipe';
+
+@Component({
+    standalone: true,
+    selector: 'tr[tuiDocAPIItem]',
+    imports: [
+        FormsModule,
+        NgForOf,
+        NgIf,
+        NgSwitch,
+        NgSwitchCase,
+        TuiChevron,
+        TuiDataListWrapper,
+        TuiDocTypeReferencePipe,
+        TuiIcon,
+        TuiInputNumberModule,
+        TuiInspectPipe,
+        TuiSwitch,
+        TuiTextfield,
+        TuiTextfieldControllerModule,
+    ],
+    templateUrl: './api-item.template.html',
+    styleUrls: ['./api-item.style.less'],
+    changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TuiDocAPIItem<T> {
+    @Input()
+    public name = '';
+
+    @Input()
+    public type = '';
+
+    @Input()
+    public value?: T;
+
+    @Input()
+    public items: readonly T[] = [];
+
+    @Output()
+    public readonly valueChange = new EventEmitter<T>();
+}

projects/addon-doc/components/api/api-item.style.less

@@ -0,0 +1,76 @@
+@import '@taiga-ui/core/styles/taiga-ui-local';
+
+:host {
+    box-shadow: inset 0 -1px var(--tui-border-normal);
+}
+
+.t-td {
+    padding: 1.5rem 2rem 1.5rem 0;
+    vertical-align: top;
+
+    &:last-child {
+        padding-inline-end: 0;
+        text-align: end;
+    }
+}
+
+.t-name {
+    display: flex !important;
+    min-block-size: 1.5rem;
+    inline-size: fit-content;
+    margin: 0 0 0.5rem !important;
+    -webkit-text-fill-color: var(--tui-background-accent-2-pressed);
+
+    &_input {
+        -webkit-text-fill-color: var(--tui-text-negative);
+    }
+
+    &_banana {
+        -webkit-text-fill-color: var(--tui-text-action);
+    }
+
+    &_output {
+        -webkit-text-fill-color: var(--tui-status-info);
+    }
+}
+
+.t-type {
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: flex-start;
+    min-block-size: 1.5rem;
+    margin: 0 !important;
+}
+
+.t-reference {
+    display: inline-flex;
+    color: var(--tui-text-action);
+    text-decoration: none;
+    align-items: center;
+    justify-content: center;
+    gap: 3px;
+}
+
+.t-input {
+    min-inline-size: 10rem;
+    margin-block-start: -0.625rem;
+}
+
+@media @tui-mobile {
+    :host {
+        gap: 1rem;
+        padding: 1rem 0;
+    }
+
+    .t-td {
+        padding: 0;
+
+        &:last-child {
+            text-align: start;
+        }
+    }
+
+    .t-input {
+        margin: 0;
+    }
+}

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

@@ -0,0 +1,97 @@
+<td class="t-td">
+    <code
+        class="t-name"
+        [class.t-name_banana]="name.startsWith('[(')"
+        [class.t-name_input]="name.startsWith('[')"
+        [class.t-name_output]="name.startsWith('(')"
+    >
+        {{ name }}
+    </code>
+    <ng-content />
+</td>
+<td class="t-td">
+    <code class="t-type">
+        <ng-container *ngFor="let item of type | tuiDocTypeReference; let last = last">
+            <a
+                *ngIf="item.reference; else default"
+                target="_blank"
+                class="t-reference"
+                [attr.href]="item.reference"
+            >
+                {{ item.type }}
+                <tui-icon
+                    icon="@tui.external-link"
+                    [style.font-size.rem]="1"
+                />
+            </a>
+            <ng-template #default>
+                {{ item.type }}
+            </ng-template>
+            <span *ngIf="!last">&nbsp;|&nbsp;</span>
+        </ng-container>
+    </code>
+</td>
+<td class="t-td">
+    <tui-textfield
+        *ngIf="items.length; else noItems"
+        tuiChevron
+        tuiTextfieldSize="m"
+        class="t-input"
+        [content]="content"
+        [tuiTextfieldCleaner]="type.includes('null')"
+    >
+        <select
+            placeholder="null"
+            tuiTextfield
+            [ngModel]="value ?? null"
+            (ngModelChange)="valueChange.emit($event)"
+        ></select>
+        <tui-data-list-wrapper
+            *tuiTextfieldDropdown
+            [itemContent]="content"
+            [items]="items"
+        />
+    </tui-textfield>
+    <ng-template
+        #content
+        let-data
+    >
+        <code [style.margin]="0">{{ data | tuiInspectAny }}</code>
+    </ng-template>
+    <ng-template #noItems>
+        <ng-container [ngSwitch]="type">
+            <input
+                *ngSwitchCase="'boolean'"
+                tuiSwitch
+                type="checkbox"
+                [id]="name"
+                [ngModel]="value"
+                (ngModelChange)="valueChange.emit($event)"
+            />
+
+            <tui-textfield
+                *ngSwitchCase="'string'"
+                tuiTextfieldSize="m"
+                class="t-input"
+            >
+                <input
+                    tuiTextfield
+                    [id]="name"
+                    [ngModel]="value || ''"
+                    (ngModelChange)="valueChange.emit($event)"
+                />
+            </tui-textfield>
+
+            <tui-input-number
+                *ngSwitchCase="'number'"
+                tuiTextfieldSize="m"
+                class="t-input"
+                [nativeId]="name"
+                [ngModel]="value"
+                [step]="1"
+                [tuiTextfieldLabelOutside]="true"
+                (ngModelChange)="valueChange.emit($event || 0)"
+            />
+        </ng-container>
+    </ng-template>
+</td>

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

@@ -0,0 +1,19 @@
+import {
+    ChangeDetectionStrategy,
+    Component,
+    inject,
+    ViewEncapsulation,
+} from '@angular/core';
+import {TUI_DOC_DOCUMENTATION_TEXTS} from '@taiga-ui/addon-doc/tokens';
+
+@Component({
+    standalone: true,
+    selector: 'table[tuiDocAPI]',
+    templateUrl: './api.template.html',
+    styleUrls: ['./api.style.less'],
+    encapsulation: ViewEncapsulation.None,
+    changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TuiDocAPI {
+    protected readonly texts = inject(TUI_DOC_DOCUMENTATION_TEXTS);
+}

projects/addon-doc/components/api/api.style.less

@@ -0,0 +1,38 @@
+@import '@taiga-ui/core/styles/taiga-ui-local';
+
+[tuiDocAPI] {
+    inline-size: 100%;
+
+    tbody [tuiTitle] {
+        align-items: flex-start;
+        color: var(--tui-text-secondary);
+        padding: 1rem;
+        box-shadow: 0 1px var(--tui-border-normal);
+        background: var(--tui-background-base-alt);
+    }
+
+    th {
+        padding: 0.5rem 0;
+        color: var(--tui-text-secondary);
+        font-weight: normal;
+        text-align: start;
+        box-shadow: inset 0 -1px var(--tui-border-normal);
+
+        &:last-child {
+            text-align: end;
+        }
+    }
+}
+
+@media @tui-mobile {
+    [tuiDocAPI],
+    [tuiDocAPI] tbody,
+    [tuiDocAPI] tr {
+        display: flex;
+        flex-direction: column;
+
+        th {
+            display: none;
+        }
+    }
+}

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

@@ -0,0 +1,8 @@
+<thead>
+    <tr>
+        <th>{{ texts[2] }}</th>
+        <th>{{ texts[1] }}</th>
+        <th>{{ texts[3] }}</th>
+    </tr>
+</thead>
+<ng-content />

projects/addon-doc/components/index.ts

@@ -1,3 +1,5 @@
+export * from './api/api.component';
+export * from './api/api-item.component';
 export * from './code';
 export * from './copy';
 export * from './demo';

projects/addon-doc/index.ts

@@ -1,4 +1,6 @@
 import {
+    TuiDocAPI,
+    TuiDocAPIItem,
     TuiDocCode,
     TuiDocCopy,
     TuiDocDemo,
@@ -16,6 +18,8 @@ import {
 import {TuiDocText} from '@taiga-ui/addon-doc/directives';
 
 export const TuiAddonDoc = [
+    TuiDocAPI,
+    TuiDocAPIItem,
     TuiDocCopy,
     TuiDocTab,
     TuiDocDemo,

projects/addon-doc/tokens/i18n.ts

@@ -22,16 +22,19 @@ export const TUI_DOC_DEMO_TEXTS = tuiCreateToken<[string, string, string]>([
  * @string word 'type',
  * @string 'name and description',
  * @string word 'value'
- * @string message for tooltip about ng-polymorpheus
+ * @string @deprecated message for tooltip about ng-polymorpheus
  * ]
  */
 export const TUI_DOC_DOCUMENTATION_TEXTS = tuiCreateToken<
-    [string, string, string, string, string]
+    [argument: string, type: string, name: string, value: string, tooltip: string]
 >([
     'Argument',
     'Type',
     'Name and description',
     'Value',
+    /**
+     * @deprecated
+     */
     'Learn about our dynamic templates from ',
 ]);
 

projects/cdk/constants/used-icons.ts

@@ -19,6 +19,7 @@ export const TUI_USED_ICONS = [
     '@tui.union-pay',
     '@tui.uzcard',
     '@tui.verve',
+    '@tui.external-link',
     '@tui.search',
     '@tui.sun',
     '@tui.moon',

projects/core/components/textfield/textfield.component.ts

@@ -31,6 +31,7 @@ import {
 } from '@taiga-ui/core/directives/dropdown';
 import {TuiWithIcons} from '@taiga-ui/core/directives/icons';
 import {TUI_COMMON_ICONS} from '@taiga-ui/core/tokens';
+import type {TuiSizeL, TuiSizeS} from '@taiga-ui/core/types';
 import type {PolymorpheusContent} from '@taiga-ui/polymorpheus';
 import {PolymorpheusOutlet} from '@taiga-ui/polymorpheus';
 
@@ -60,6 +61,7 @@ import {TuiWithTextfieldDropdown} from './textfield-dropdown.directive';
         '[style.--t-side.px]': 'side',
         '[attr.data-size]': 'options.size()',
         '[class._with-label]': 'hasLabel',
+        '[class._with-template]': 'content',
         '[class._disabled]': 'el?.nativeElement.disabled',
     },
 })
@@ -107,6 +109,10 @@ export class TuiTextfieldComponent<T> implements TuiDataListHost<T> {
         return this.el?.nativeElement.id || this.autoId;
     }
 
+    public get size(): TuiSizeL | TuiSizeS {
+        return this.options.size();
+    }
+
     public handleOption(option: T): void {
         this.directive?.setValue(this.stringify(option));
         this.open.set(false);

projects/core/components/textfield/textfield.directive.ts

@@ -58,8 +58,8 @@ export class TuiTextfieldBase {
         return null;
     }
 
-    public setValue(value: string): void {
-        this.el.value = value;
+    public setValue(value: string | null): void {
+        this.el.value = value || '';
         this.el.dispatchEvent(new Event('input', {bubbles: true}));
     }
 }