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}));
  }
 }